Errors
scope_denied
403 — the token authenticated successfully but its scope policy does not permit the requested operation on the targeted resource.
Last updated
Cause
Matter returns scope_denied when the token's declared scope policy explicitly forbids the operation. Every token carries a scope DSL document that names the resources and verbs it can touch — read entities, write to a single entity, list filings for a portfolio, and so on. The token-scope evaluator runs at the start of every request, before any business logic, and a denial here means the policy excludes either the resource type, the verb, or the specific resource id.
The denial is intentional and recorded in the audit log. Repeated denials within a short window are a signal that an agent is exceeding its mandate; observability dashboards surface a scope_denied rate per token. Matter never broadens scope implicitly — the policy on the token is the entire universe of actions that token can take.
Fix
- Read the scope policy attached to the token via
retrieveToken. The response includes thepolicydocument. - Compare the policy to the operation that was rejected. The
detailon the problem response names the resource and verb that were denied. - If the operation is legitimately required, mint a new token whose policy includes the missing scope. Do not edit the existing token's policy in place — tokens are append-only, and broadening scope retroactively defeats the audit trail.
- If the operation is not required, the calling agent has overreached. Fix the agent, not the token.
Related codes
scope_tier_insufficient— the operation is allowed by the policy but blocked by the token's tier.scope_resource_out_of_portfolio— the policy permits the verb but not on this specific resource.auth_token_revoked— the token is dead entirely.