scope_resource_out_of_portfolio

Last updated Jun 14, 2026

Cause

Matter supports portfolios — named collections of entities that a token can be bound to. A token scoped to a single portfolio can list, read, and operate on the entities inside that portfolio but is denied access to entities outside it. scope_resource_out_of_portfolio fires when the verb and resource type are both permitted but the specific resource id resolves outside the bound portfolio.

This is the portfolio-aware cousin of scope_denied. The verb-and-resource check would pass on its own; the portfolio check is what fails. It commonly appears in fund or VC contexts where a single agent has tokens scoped to one portfolio per company, and the agent attempts an action with the wrong token in flight.

Fix

1. Confirm which portfolio the targeted resource belongs to. Read the entity's portfolio_id via retrieveEntity.
2. Confirm which portfolio the token is bound to. Read the token's portfolio_id via retrieveToken. A null portfolio means the token is account-wide.
3. If the two should match but don't, the operation is being executed with the wrong credential. Route through your token-selection layer to pick the token whose portfolio matches the target resource.
4. If the resource genuinely needs to be reachable from this token, mint a new token bound to the correct portfolio (or to no portfolio, for account-wide tooling). Never silently broaden an existing token.

Related codes

• scope_denied — the resource scope or verb itself is denied.
• not_found_portfolio — the portfolio id on the token doesn't resolve.
• not_found_resource — the resource id doesn't resolve at all.

API reference

• Tokens — /api-reference/tokens
• Portfolios — /api-reference/portfolios