{% extends "_layout.html" %} {% set title = "Insufficient scope" %} {% set status = "403 Forbidden" %} {% set description = "Your access token is valid but was not minted with the scope this endpoint requires. The registered scopes, and why a refresh will not help." %} {% block main %}
Your access token is valid, unexpired and correctly bound to your key — and it was not minted with the scope this endpoint requires.
Do not refresh. A refresh re-mints a token with the same scope ceiling, so it
produces this answer again. This is the usual mistake: the status is 403 and the header
looks like an auth failure, and a client that treats it as one loops.
scope parameter of the WWW-Authenticate header. It names
the scope you needed.HTTP/1.1 403 Forbidden
WWW-Authenticate: DPoP error="insufficient_scope", scope="artifacts:read"
Content-Type: application/problem+json
This is the only WWW-Authenticate in the API that does not ride on a
401. A client that inspects that header only on 401 responses will miss it
entirely. RFC 6750 registers
insufficient_scope as a 403.
| Scope | Covers |
|---|---|
jobs:read |
GET /v1/jobs, GET /v1/jobs/{id},
…/artifacts — the artifact listing — and
…/logs, a node's live log |
jobs:write |
POST /v1/jobs, …/upload-grant,
…/submit, …/cancel. Carries jobs:read |
jobs:delete |
DELETE /v1/jobs/{id}. Carries jobs:read |
artifacts:read |
GET /v1/jobs/{id}/artifacts/{artifact_id} — the bytes,
every kind |
devices:read | GET /v1/devices,
GET /v1/devices/{id} |
devices:write | DELETE /v1/devices/{id} — a revoke.
Carries devices:read |
profile:read | GET /v1/me |
:write carries :read for the same resource, and jobs:delete
carries jobs:read — never across resources. The expansion is applied when the
token is minted, so the scope in your token response already lists both: ask for
jobs:write and you are granted jobs:read jobs:write. Only registered
scopes are granted, v1 may register more, and none is ever administrative.
artifacts:read is the one that surprises people. It is deliberately
not part of jobs:read: a client that submits jobs and watches them finish does not need
to pull the outputs, and artifact bytes are where restricted collateral lives. Listing artifacts
needs jobs:read; fetching one needs artifacts:read.
Logs are the documented exception. An archived log is an artifact, so
…/artifacts/{artifact_id} serves it under artifacts:read like any
other kind — but …/logs serves the same bytes under jobs:read,
because watching a run is what a submitting client is for. If you can submit and watch, you can read
your logs; you still cannot pull your deliverables.
{
"type": "https://sc.example.com/server-errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This endpoint requires the artifacts:read scope.",
"instance": "/v1/jobs/01J9.../artifacts/01J9...",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
No required extension members. The scope you need is in the header.
{% include "_help.html" %}entitlement-denied is the same status and a
different question: may this account consume this thing, rather than
may this credential attempt this call. Widening your token will never fix
that one, and being entitled will never fix this one.
invalid-token (401) means the token itself is expired or unverifiable.
That one you refresh. This one you cannot.
session-ended (401) means the session is over and you must log in again
— which, as it happens, is also what fixes this, but for an unrelated reason.