> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fiveninelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# missing_scope

> 403 permission — the key is valid but doesn't carry the scope this call needs.

**HTTP 403 · type `permission`.** The key authenticated, but its scopes don't cover
this call. Keys carry four scopes: `runs:write` (spending POSTs — sessions, turns,
refreshes, extractions, monitors, stop), `runs:read` (all run reads and
`/v1/discover`), `webhooks:manage` (endpoint CRUD, attempts, test deliveries), and
`account:read` (`/v1/me`, `/v1/balance`, `/v1/usage`, `/v1/keys`). The default pair
minted at signup carries all of them; scoped-down keys are minted in the dashboard.
Nothing ran and nothing was charged.

## The shape

```json theme={null}
{
  "error": {
    "type": "permission",
    "code": "missing_scope",
    "message": "This call requires runs:write; the key carries runs:read.",
    "doc_url": "https://docs.fiveninelabs.com/errors/missing_scope",
    "request_id": "req_5tt18e",
    "required_scope": "runs:write"
  }
}
```

## How to fix

* `required_scope` names what's missing. Either use a key that carries it, or mint
  one in the dashboard with the right scopes — scopes are fixed at mint, not
  editable.
* Check what the current key carries with `GET /v1/me` (needs `account:read`).
* If you scoped a key down on purpose (e.g. a read-only key for a reporting job),
  this error working as intended is the confirmation.

## Reproduce it

Mint a key with only `runs:read` in the dashboard, then try to spend with it:

```bash theme={null}
curl https://api.fiveninelabs.com/v1/sessions \
  -H "Authorization: Bearer $READ_ONLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "vinyl records under $30", "max_spend_usd": 1}'
```