Glossary

insufficient_scope

insufficient_scope is the 403 error returned when a key lacks the scope a call needs. OneLifeVibe checks platform scopes and the key's world list.

Updated November 12, 2026

Standard
RFC 6750

At OneLifeVibe

Related terms

What it means

insufficient_scope is the error value RFC 6750 defines for a 403 response. The token is real and the caller is authenticated, but the permission the endpoint requires is not attached to that token. Sending the same request again with the same credential gets the same answer.

The distinction matters when you read logs. A 401 with invalid_token means the credential is missing, expired or wrong. A 403 with insufficient_scope means the credential was accepted and then found too narrow. A 403 carrying a different code means something else again, so read the code before you change anything.

How it works

A protected endpoint names the scope it needs. The authorization server issues the token with some set of scopes, and the resource server compares the two on every call. If the required scope is absent, the call stops before any work is done.

RFC 6750 says the response can carry a WWW-Authenticate header with error="insufficient_scope" and a scope parameter naming what was required. Read that header, widen the grant through your authorization flow, and try once more. Do not build an automatic retry loop, because waiting adds nothing. If your client cannot request that scope at all, the fix belongs in the authorization request, not in the request that failed.

How OneLifeVibe uses it

OneLifeVibe grants platform scopes to API keys: worlds:read, tools:read, tools:invoke, events:read, events:subscribe and data:read. Each key also carries a world list, either "*" or keys such as ["wuuuh","soclasica"]. A call succeeds only when the scope and the world both allow it. The scope decides what the call may do. The world list decides where it may do it.

When the scope is missing you get 403 insufficient_scope. When the scope is present but the world is not in the key's list, the answer is 403 world_not_allowed. Both are permission answers, and both call for a different key rather than a different request body. Use the codes to tell them apart, since they point at different edits.

Common mistakes

Retrying after insufficient_scope with the same key, or adding a delay, changes nothing. The request is not failing from load. The grant is too narrow.

Another common slip is widening the world list when the scope is the problem. Setting the list to "*" does not add tools:invoke to a key that never had it, and it hands out reach you may not have planned for. Read the code first.

Teams also treat every 403 as one thing. insufficient_scope and world_not_allowed are separate codes with separate fixes, and a token problem will usually show up as 401 rather than 403.

Questions

What is the difference between insufficient_scope and invalid_token?

invalid_token comes back on a 401 when the credential is missing, expired or wrong. insufficient_scope comes back on a 403 when the credential was accepted but lacks the permission the call needs. One means fix the token, the other means change what the token is allowed to do.

Does a star in my key's world list give it every scope?

No. The world list decides where a key can act, and the platform scopes decide what it can do. A key with "*" and only worlds:read still gets 403 insufficient_scope on a tools:invoke call.

See it working. The OneLifeVibe connector and Platform API put these pieces together.

Get a free key Read the docs

Written from the OneLifeVibe tool registry and platform configuration, and checked automatically before publishing. Something wrong? Tell us.