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

# Missing OAuth scope (SCOPE_INSUFFICIENT)

> The OAuth grant that issued this bearer is missing a scope the tool requires.

## What it means

Aeris uses fine-grained OAuth scopes. Most mutating tools require an `apply` scope on top of the default `read` scope. If a caller with a read-only grant invokes a mutating tool, the request fails with `SCOPE_INSUFFICIENT`. The user must re-consent to add the missing scope — refreshing the token alone will not help.

## How to fix

* Compare `details.required` with `details.granted` to see which scopes are missing.
* Redirect the user through the OAuth consent flow again with the extended scope set.
* Store the refreshed grant; the same tool call should then succeed.

## Response envelope

```json theme={"dark"}
{
  "ok": false,
  "error_envelope": {
    "code": "SCOPE_INSUFFICIENT",
    "message": "The current grant is missing a required scope.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/scope-insufficient",
    "retryable": false,
    "retry_after_ms": null,
    "details": {
      "required": ["read", "apply"],
      "granted": ["read"]
    }
  }
}
```

## Related

* [`AUTH_EXPIRED`](/mcp/errors/auth-expired) — refresh solves it; here, re-consent is needed.
* [`ENTITLEMENT_LOCKED`](/mcp/errors/entitlement-locked) — also 403, but blocked by plan rather than by scope.
* [`VIEWER_READ_ONLY`](/mcp/errors/viewer-read-only) — admin view-as sessions cannot mutate regardless of scope.