Skip to main content

​
scope_missing

An endpoint’s listed scopes are all required. When a single named scope is the one you are missing, the message names it alongside everything the endpoint requires, and details.required_scope repeats that one scope for programmatic use. Do not rely on it being there for every scope_missing: a refusal on a group of alternatives, and a version-gated refusal like the POST /v1/uploads example below, carry no details at all — read message in those cases. Branch on error.code, never on error.message. The message is human-facing prose meant for your logs and your own error surfaces; its wording is not part of the API contract and can change without a version bump. scope_missing is the stable signal. A <resource>:write scope satisfies a <resource>:read requirement, so a write-only key is never locked out of reading its own resource. That is the only implication — holding a read scope never satisfies a write requirement. For example, POST /v1/notes requires notes:write. A key holding only notes:read returns:
An endpoint that requires more than one scope names all of them. For example PATCH /v1/posts/{postId}/media requires posts:write and media:read; a key holding only media:read returns Token lacks posts:write. This endpoint requires all of: posts:write, media:read. Where an endpoint accepts alternatives it says so rather than leaving you to guess. POST /v1/uploads takes sources:write or knowledge:write, and returns As of API version 2026-08-10 this endpoint requires one of: sources:write, knowledge:write. Re-mint the key with that scope, or pin Scripe-Api-Version: 2026-08-01 until you can. To recover, edit the key in Settings → Developer → API keys and tick the missing scope. Edits take effect on the next request — we bust the auth cache on save; if that invalidation fails the cache TTL bounds the lag at 5 minutes.

​
On an OAuth connection (MCP)

There is no key to edit: the grant is fixed at consent time, so the message names the only repair there is and says that retrying cannot work.
The second sentence appears only for the never-implied family — posts:publish, settings:write and every *:destroy scope. They sit outside the read / write aliases and outside every implication, so a consent granted before one of them existed never gains it on deploy day. Holding posts:write is not evidence that posts:destroy should have been granted. See auth.md §1.2 for the scope catalogue.