Mint a portfolio-scoped token

Last updated Jun 14, 2026

Bind an agent token to one portfolio. The key operates that portfolio's member entities end-to-end; everything else returns 403, and other portfolios' resources are invisible.

Trigger

You're delegating one portfolio — to an end customer's integration, a fund team, or an agent — and the blast radius has to end at the portfolio's edge.

Call sequence

1. Mint the scoped token with your org key

POST /v1/tokens  { tier, portfolio_id, principal, ... }

2. Operate member entities with the scoped key

POST /v1/entities  { portfolio_id, ... }   // must match the bound portfolio

Idempotency

Token creation idempotent via `Idempotency-Key`.

Errors

Related

The call

Pass portfolio_id on the standard token-creation body. Everything else — tier, principal binding, acknowledgements — works exactly as for an unscoped token:

{
  "tier": 3,
  "portfolio_id": "pf_S4dGqL2c",
  "principal": { "human_id": "usr_4Kj2m8pQ" },
  "api_version": "2026-06-10",
  "acknowledgements": [
    { "slug": "not_legal_advice", "stakeholder_id": "stk_Qw5xY2bR" },
    { "slug": "agent_action_binds_principal", "stakeholder_id": "stk_Qw5xY2bR" }
  ]
}

Two rules govern the chain of custody:

• Only an unscoped org key can mint. A portfolio-scoped key cannot create or rotate tokens — createToken is outside its allowed set, so the attempt returns 403 portfolio_scope_denied. Scope cannot widen itself.
• Rotation preserves the binding. When your org key rotates a scoped token, the replacement carries the same portfolio_id — the attribution chain stays intact.

What the scoped key can do

The allowed set is deliberately narrow in v1:

• Its own portfolio, read-side — retrieve the bound portfolio, page its member list, pull the compliance rollup. GET /v1/portfolios returns only the bound portfolio.
• Member entities, end-to-end — create entities into the bound portfolio (portfolio_id on the body must match), read and submit them, create and read filings, read entity compliance views, documents, stakeholders, and grants.

Everything else returns 403 portfolio_scope_denied: creating or updating portfolios, attaching or detaching members, batch formation (an org-key operator action), minting or rotating tokens, webhook endpoints, agent policies, search, event listings, reports, and account operations. The 403 is a loud, named denial — the caller holds a real credential that lacks the privilege, and should know it.

What the scoped key cannot see

Cross-portfolio probes fail differently — opaquely. An entity, filing, or document that belongs to a different portfolio returns 404 not_found, byte-identical to an id that never existed. A scoped key cannot enumerate, confirm, or time-probe its way to learning what else lives in the org.

403 portfolio_scope_denied  →  known operation, insufficient privilege
404 not_found               →  the resource does not exist, for you

Variations

const portfolio = await matter.portfolios.create({
  name: `Customer ${customer.id}`,
  metadata: { customer_id: customer.id },
});

const token = await matter.tokens.create({
  tier: 3,
  portfolio_id: portfolio.id,
  principal: { human_id: operatorUserId },
  api_version: "2026-06-10",
  acknowledgements,
});
// store token alongside the customer; revoke at offboarding

const fundTwoKey = await matter.tokens.create({
  tier: 3,
  portfolio_id: "pf_FundII",
  principal: { human_id: fundTwoLeadId, agent_id: "agt_FundIIOps" },
  api_version: "2026-06-10",
  acknowledgements,
});

Related

• Create a token — full request schema and acknowledgement slugs
• Tenancy: portfolios — the multi-tenancy model the binding builds on
• Build a portfolio dashboard — the rollup reads in the allowed set
• Agents and tokens — the four-tier token model