Platform API error
insufficient_scope
insufficient_scope is a 403 error returned when your API key lacks the scope an endpoint requires. Create a new key with that scope and rotate to it.
Updated November 6, 2026
- HTTP status
- 403
- Code
insufficient_scope
Returned when
- GET /worlds needs worlds:read, GET /tools needs tools:read, POST /tools/:name needs tools:invoke, GET /events needs events:read, creating or deleting subscriptions needs events:subscribe.
What to do
- Create a key with the missing scope in the console (scopes cannot be added to an existing key) and rotate to it.
Example answer
HTTP/1.1 403
content-type: application/json
{
"error": {
"code": "insufficient_scope",
"message": "This key needs tools:invoke."
}
}Related errors
- world_not_allowed The key's world list does not include this world.
- missing_credentials No API key was sent.
What it means
The Platform API returns insufficient_scope with HTTP status 403 when the API key on the request does not hold the scope the endpoint requires. The request carries a key, but that key is not authorized for this operation, so the call is refused instead of executed.
Every error response carries a code, a message and a hint. The code is stable across releases; the message and hint are not. Compare against insufficient_scope exactly and keep the human-readable text out of your branching logic.
Why you are seeing it
Each endpoint requires a specific scope. GET /worlds needs worlds:read. GET /tools needs tools:read. POST /tools/:name needs tools:invoke. GET /events needs events:read. Creating or deleting a subscription needs events:subscribe.
In most cases the key was created for a narrower job than the call you are now making, such as a key issued for reading events being used against POST /tools/:name. The message names the missing scope, for example This key needs tools:invoke. or This key needs events:subscribe.
How to fix it
Scopes cannot be added to an existing key. Open the console, create a key that includes the missing scope, and rotate your integration to it before retrying the request.
If the endpoint you are calling needs more than one scope, put all of them on the new key in one pass. Deploy the new key to your environment, confirm the request succeeds, then retire the old one.
If the scope named in the message does not match what you meant to do, recheck the route. POST /tools/:name invokes a tool and needs tools:invoke, while listing tools with GET /tools needs tools:read.
Handling it in code
Treat this 403 as a configuration problem, not a transient one. Retrying with the same key produces the same response, so do not place it behind a backoff loop. Log the code, the route and the scope named in the message, then hand it to whoever manages your API keys.
Branch on the code string, not the message. Matching insufficient_scope is reliable; matching text such as This key needs events:read. is not, because it changes with the endpoint.
Other codes you may run into in the same area are world_not_allowed and missing_credentials. Read their own reference entries before deciding how to handle them.
Questions
What HTTP status code comes with insufficient_scope?
403. The request reached the API with a key, but that key does not hold the scope the endpoint requires, so the call is refused rather than processed.
Can I add the missing scope to my current API key?
No. Scopes cannot be added to an existing key. Create a new key in the console that includes the missing scope and rotate your integration to it.
Which scope does GET /events need?
events:read, with the message This key needs events:read. when it is absent. Creating or deleting subscriptions instead needs events:subscribe.
Keys, plans and usage live in the console: rotate keys, add webhook endpoints, see the last 30 days.
Written from the OneLifeVibe tool registry and platform configuration, and checked automatically before publishing. Something wrong? Tell us.