Skip to content
deedglassdocs

insufficient_scope

Step 9: the API key is valid and active, but lacks a scope the endpoint lists.

HTTP 403 · permission_error · not retryable

What happened

Section titled “What happened”

Step 9: the API key is valid and active, but lacks a scope the endpoint lists. The pipeline checks every scope the route declares and names the first one missing. Scopes are actions:execute, actions:read, deeds:read, actions:undo and admin (AGENTS.md §2). An agent key on any route that manages agents or keys gets this code with its own message, because no agent key changes any agent, including its own. The response carries WWW-Authenticate: Bearer realm="deedglass", error="insufficient_scope", scope="<scope>".

What to do

Section titled “What to do”

Create a key with the scope named in the message, or use a key that already has it. To manage agents, use an org admin key or the Console.

Example

Section titled “Example”
HTTP 403 · insufficient_scope
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This key doesn't have the deeds:read scope. Create a key with deeds:read in Console › Agents.",
    "param": null,
    "request_id": "req_01j9zr3m5k8q2w7x4t6v0b1c9d",
    "doc_url": "https://docs.deedglass.com/errors/insufficient_scope"
  }
}

The message is for a person and can get more exact over time: branch on type and code, never on the message.

In the SDKs

Section titled “In the SDKs”
SDK Raised as
TypeScript (@deedglass/sdk) PermissionDeniedError with code === "insufficient_scope"
Python (deedglass) deedglass.PermissionDeniedError with .code == "insufficient_scope"
Section titled “Related”