Agents

Last updated Jun 14, 2026

Matter is built so a software agent can do anything a human principal can do — file a Delaware C-Corp, run an annual report cascade, advance an M&A deal — with exactly the supervision the human chose, and a complete audit trail naming both parties for the regulator. The model uses tool-side scoping (which actions an agent can call, aligned with the MCP authorization spec) and resource-side scoping (which resources it can act on, aligned with OAuth 2.1 scope conventions); the structured-policy DSL is the layer that ties them together.

This page is the canonical reference for that model. If you want the resource shapes, jump to /api/auth/tokens and /api/authorizations/index. If you want the protocol semantics — tiers, scope, attribution, pausing, MCP catalog visibility — read on.

The 4-tier model

Every tok_… carries a tier between 1 (observe) and 4 (autonomous). Tier is a property of the token, not of the request. The same caller cannot "upgrade" mid-call — they re-mint a higher-tier token, optionally with stricter scopes, and the upgrade itself is auditable.

A few rules apply across all tiers:

• Hardcoded destructive ops never autopilot. Dissolution (/dissolve), M&A close (/corporate_transactions/{id}/close), token revocation, and registered-agent change always pause on Authorization regardless of tier.
• Tier is monotonic with respect to MCP visibility. A tier-1 token never sees a write tool in the MCP catalog — not even greyed-out. The agent cannot attempt an action it cannot describe.
• Tier downgrades are free. A tier-4 token can voluntarily call with ?dry_run=true and behave like a tier-2. Tier upgrades require a new token.
• No per-request elevation. There is no Sudo header. If you need a one-off elevated action, mint a single-action tier-3 token, use it, revoke it.

Why tier 3 is the working tier

Tier 3 is the sweet spot for production agents — the agent drives the workflow end-to-end, but every consequential mutation gates on a human signature. The human sees a single Authorization page in the dashboard with the canonical payload, the action, the agent identity, and an "Approve" button. They are not asked to read the agent's reasoning trace; they are asked to sign the artifact.

When to reach for tier 4

Tier 4 is for ops that are routine, capped, and reversible:

• annual reports and franchise-tax payments (capped by limits.max_spend_per_month)
• BOI updates triggered by stakeholder changes
• mail acknowledgement (non-escalated categories only)
• compliance reminders and renewal queueing

Tier 4 is not appropriate for:

• equity issuance (always pauses)
• any document with a wet signature requirement
• M&A workflow advancement past due_diligence
• dissolution of any kind

The policy DSL below is how you declare a tier-4 token's surface precisely.

Structured scope policy DSL

Every token carries a scopes array. Each entry is a structured policy node with five keys:

{
  "scopes": [
    {
      "allow": ["entities.read", "filings.create"],
      "resources": ["ent_Nq3KcAbc"],
      "conditions": { "livemode": false },
      "limits": { "max_calls_per_hour": 60, "max_cost_usd": 0 }
    }
  ]
}

Verbs are namespaced by resource. The canonical catalog (full list in the OpenAPI spec under each operation's x-matter-mcp.tool_name):

Evaluation order, per request:

If no entry matches, the request fails closed with 403 forbidden and the error body's extension.reason names the missing verb-resource pair so the caller can ask for the right grant.

Worked policy examples

{
  "tier": 1,
  "principal": { "human_id": "usr_4Kj2m8pQ", "agent_id": "agt_invreader" },
  "scopes": [
    {
      "allow": [
        "entities.read",
        "entities.list",
        "stakeholders.read",
        "stakeholders.list",
        "share_classes.read",
        "share_classes.list",
        "grants.read",
        "grants.list",
        "valuations.read",
        "cap_tables.read"
      ],
      "resources": ["pf_studio_fund_i"],
      "limits": { "max_calls_per_hour": 600 }
    }
  ],
  "api_version": "2026-05-01"
}

{
  "tier": 2,
  "principal": { "human_id": "usr_4Kj2m8pQ", "agent_id": "agt_paralegal_v2" },
  "scopes": [
    {
      "allow": [
        "entities.read",
        "filings.read",
        "filings.list",
        "filings.create",
        "documents.read",
        "documents.list",
        "documents.create",
        "intents.create",
        "intents.read"
      ],
      "resources": ["ent_*"],
      "conditions": { "request.dry_run": true }
    }
  ],
  "api_version": "2026-05-01"
}

{
  "tier": 3,
  "principal": { "human_id": "usr_4Kj2m8pQ", "agent_id": "agt_cos" },
  "scopes": [
    {
      "allow": [
        "entities.*",
        "filings.*",
        "documents.*",
        "grants.*",
        "valuations.*",
        "resolutions.*",
        "stakeholders.*",
        "mail.*"
      ],
      "deny": ["entities.dissolve", "tokens.revoke", "tokens.rotate"],
      "resources": ["ent_Nq3KcAbc"],
      "limits": { "max_calls_per_hour": 240 }
    }
  ],
  "api_version": "2026-05-01"
}

{
  "tier": 4,
  "principal": { "human_id": "usr_4Kj2m8pQ", "agent_id": "agt_compliance" },
  "scopes": [
    {
      "allow": [
        "entities.read",
        "filings.read",
        "filings.list",
        "filings.create",
        "tax_profiles.read",
        "tax_profiles.update",
        "mail.acknowledge"
      ],
      "resources": ["ent_*"],
      "conditions": {
        "filing.type": ["annual_report", "franchise_tax", "boi_update"],
        "mail.category": ["routine_correspondence"]
      },
      "limits": {
        "max_cost_usd": 5000,
        "max_filings_per_quarter": 12,
        "max_calls_per_hour": 60
      }
    }
  ],
  "api_version": "2026-05-01"
}

{
  "tier": 4,
  "principal": { "human_id": "usr_studio_admin", "agent_id": "agt_studio_ops" },
  "scopes": [
    {
      "allow": [
        "entities.read", "entities.list",
        "filings.read", "filings.list",
        "compliance.read",
        "cap_tables.read",
        "stakeholders.read", "stakeholders.list",
        "grants.read"
      ],
      "resources": ["pf_studio_fund_i"],
      "limits": { "max_calls_per_hour": 1200 }
    },
    {
      "allow": ["filings.create", "tax_profiles.update"],
      "resources": ["pf_studio_fund_i"],
      "conditions": {
        "filing.type": ["annual_report", "franchise_tax"],
        "entity.jurisdiction": ["US-DE", "US-CA"]
      },
      "limits": {
        "max_cost_usd": 25000,
        "max_filings_per_quarter": 60
      }
    },
    {
      "allow": ["resolutions.create"],
      "resources": ["pf_studio_fund_i"],
      "conditions": {
        "resolution.type": ["written_consent", "ratification"]
      }
    }
  ],
  "api_version": "2026-05-01"
}

Conditions cookbook

Conditions are flexible JSON predicates. The following keys are evaluated against the resolved request:

Conditions short-circuit on first false. They are evaluated after ID matching, so an off-policy resource can never leak through a permissive condition.

Dual attribution

Every event Matter writes that originated from an agent carries both:

• human_principal_id — the human who is legally accountable for the action
• agent_id — the runtime agent identity that physically executed it

This is non-negotiable. There is no "system" actor type for agent-driven mutations. Even tier-4 autopilot writes carry the human principal — that's the whole point of the standing authorization.

{
  "id": "evt_5pQz8KrL",
  "object": "event",
  "type": "filing.submitted",
  "created": 1745539200,
  "data": {
    "object": {
      "id": "flg_2x7Vc3Mn",
      "object": "filing",
      "type": "annual_report",
      "entity_id": "ent_Nq3KcAbc",
      "status": "submitted"
    }
  },
  "authorized_by": {
    "human_principal_id": "usr_4Kj2m8pQ",
    "agent_id": "agt_compliance",
    "token_id": "tok_4Kj2m8pQ",
    "tier": 4,
    "authorization_id": null,
    "via": "standing_policy"
  },
  "sequence": 41,
  "livemode": true
}

The authorized_by envelope is denormalised onto every event, every AuditEntry, and every signed receipt. The via field disambiguates the authorization source:

Why dual-attribution

Two reasons, in priority order:

1. Regulatory traceability. Every state filing, every BOI update, every resolution carries the human's identity on the receipt — that's what state registrars, the IRS, and FinCEN expect to see if they audit. The agent identity is the secondary signal: who moved the bits, on whose behalf.
2. Reversibility. When something goes wrong, you need to be able to say "agent X took action Y on principal Z's behalf at time T" and unwind from there. Single-attribution would force you to either treat the agent as a legal person (impossible) or anonymise the action (uninvestigable).

See /api/conventions/observability for how dual attribution surfaces in distributed traces and request logs.

The Authorization resource

When a tier-3 agent invokes a destructive or high-stakes operation — or a tier-4 agent exceeds its limits cap — the API does not execute. It returns 202 Accepted with the operation in pending_authorization and embeds an Authorization resource (auth_…) in the response body.

{
  "id": "ctx_9hNm2Bxy",
  "object": "corporate_transaction",
  "stage": "due_diligence",
  "status": "pending_authorization",
  "authorization": {
    "id": "auth_8sQp4LbR",
    "object": "authorization",
    "token_id": "tok_4Kj2m8pQ",
    "action": "corporate_transactions.advance",
    "payload_hash": "sha256-d8f4…",
    "status": "pending",
    "expires_at": 1745625600,
    "signature_url": "https://app.mattermode.com/auth/auth_8sQp4LbR",
    "created": 1745539200,
    "livemode": true
  }
}

The human reviews the canonical payload (rendered from payload_hash) at signature_url, or your own UI calls POST /v1/authorizations/{id}/approve.

Lifecycle

                              ┌─ approved ─→ operation resumes ─→ <op>.* event
auth.pending  ─→ human acts ──┤
                              └─ denied   ─→ operation cancels ─→ <op>.cancelled
                              └─ expired  ─→ operation cancels ─→ <op>.cancelled
                                            (TTL, default 24h)

Approving an authorization

curl -X POST https://api.mattermode.com/v1/authorizations/auth_8sQp4LbR/approve \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "approver_stakeholder_id": "stk_ceo_alice",
    "signature_method": "esign"
  }'

The approver must be a Stakeholder on the target entity (or the account holder for account-level actions). Agents cannot be approvers — by design. See the FAQ below.

Two-of-N approval policies

For the highest-stakes operations, the policy can require multiple approvers before the authorization transitions to approved. Configured at token-creation time on the policy entry:

{
  "allow": ["entities.dissolve", "corporate_transactions.close"],
  "resources": ["ent_*"],
  "approval_policy": {
    "quorum": 2,
    "approver_role": "director",
    "min_quorum_seconds_apart": 0
  }
}

quorum: 2 requires two distinct directors. The first approval transitions the authorization to partially_approved; the second to approved. Useful for dissolution, M&A close, and large equity issuances.

Idempotency under pause

A tier-3 caller's Idempotency-Key is held for the lifetime of the authorization. If the agent retries the same key while the authorization is pending, Matter returns the same pause envelope — it does not create a second authorization. After the authorization terminates (approved / denied / expired), the idempotency record retains the final outcome for the standard 24h window. See /api/conventions/idempotency.

Payload binding

payload_hash is the SHA-256 of the canonical JSON payload (sorted keys, no whitespace) of the original request. If the client modifies the payload — even whitespace — the authorization is invalidated and the next call mints a new one. The human signs the exact artifact the API will execute, not an agent-narrated description of it.

MCP catalog visibility per tier

Matter ships an MCP server at apps/mcp/ that exposes the API as Model Context Protocol tools. The catalog is generated from the OpenAPI spec — every operation with x-matter-mcp.exposed: true becomes one tool. The token's tier filters which tools the runtime sees on tools/list.

A tier-1 token introspecting the MCP server sees only tools where read_only: true || min_tier <= 1. A tier-4 token sees the full catalog with destructive: true tools annotated as requires_authorization.

This is enforced server-side at tools/list time. The agent runtime does not choose what to expose — the token does.

See /mcp/introduction for the full MCP overview and /mcp/authentication for the OAuth 2.1 + token exchange flow.

Test mode for agents

Iterating on agent policies against the live API would be slow — multi-day state filings, real fees, real dissolutions. Test mode is built for this.

A sk_test_ key (or any test-mode tok_) operates against an isolated test-mode dataset. State filings simulate; fees do not transact. The real accelerator for agent development is X-Matter-Test-Speed:

Combine with ?auto_approve=true on a test-mode token-creation request to have all Authorization resources auto-approve immediately:

curl -X POST https://api.mattermode.com/v1/tokens \
  -H "Authorization: Bearer $MATTER_TEST_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -d '{
    "tier": 3,
    "principal": { "human_id": "usr_test", "agent_id": "agt_test" },
    "scopes": [{ "allow": ["entities.*", "filings.*"], "resources": ["ent_*"] }],
    "auto_approve": true,
    "api_version": "2026-05-01"
  }'

The test-mode token created with auto_approve: true sees every Authorization flip from pending to approved within ~50ms — perfect for end-to-end agent test suites.

See /api/conventions/test-mode for the full test-mode contract, including TestClock for time travel.

OAuth 2.1 for human-user agent clients

Claude Desktop, Cursor, Windsurf, Zed, Codex, and similar IDE / chat clients use OAuth 2.1 with PKCE to get scoped access tokens on behalf of a signed-in human. The tokens map to the same structured-policy DSL — there is no parallel scope vocabulary.

Endpoints:

• Authorization URL: https://mattermode.com/oauth/authorize
• Token URL: https://mattermode.com/oauth/token
• Revocation URL: https://mattermode.com/oauth/revoke
• Discovery: https://mattermode.com/.well-known/oauth-authorization-server

The OAuth scope parameter is a space-separated list of the same <resource>.<verb> strings used in the policy DSL. The authorization server maps the requested scopes to a synthetic tok_ under the hood, with the human-user as the human_principal_id and the OAuth client as the agent_id.

Tier mapping for OAuth flows:

Tier-4 over OAuth requires the user to explicitly confirm the spending caps and the autonomous surface during consent — the consent screen renders the policy entries verbatim, not as a marketing summary.

See /mcp/authentication for the full OAuth flow, including PKCE, refresh tokens, and the device-flow variant for headless clients.

Token lifecycle

Tokens are minted, optionally rotated, and revoked. There is no implicit expiry beyond what the caller sets via expires_at.

Minting

curl -X POST https://api.mattermode.com/v1/tokens \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "tier": 3,
    "principal": { "human_id": "usr_4Kj2m8pQ", "agent_id": "agt_cos" },
    "scopes": [
      {
        "allow": ["entities.*", "filings.*", "documents.*"],
        "deny": ["entities.dissolve"],
        "resources": ["ent_Nq3KcAbc"],
        "limits": { "max_calls_per_hour": 240 }
      }
    ],
    "expires_at": 1772150400,
    "api_version": "2026-05-01"
  }'

The response contains the one-time-shown plaintext tok_… secret. Matter never stores the plaintext — losing it means revoking and re-minting.

Rotating

POST /v1/tokens/{id}/rotate issues a new secret bound to the same id, tier, scopes, and principal. The old secret stays valid for 60 seconds to absorb in-flight requests. After 60 seconds the old secret is permanently rejected.

curl -X POST https://api.mattermode.com/v1/tokens/tok_4Kj2m8pQ/rotate \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: $(uuidgen)"

The 60-second overlap is non-configurable. Longer overlaps amplify the blast radius of a leak; shorter overlaps drop legitimate retries.

Revoking

POST /v1/tokens/{id}/revoke invalidates the token immediately. In-flight requests using the token receive 401 unauthorized on next call. Audit entries from before revocation are preserved — revocation is forward-only.

curl -X POST https://api.mattermode.com/v1/tokens/tok_4Kj2m8pQ/revoke \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01"

If the token had pending Authorization resources, they transition to expired immediately and the paused operations cancel.

Version pinning

Every token pins api_version at creation. The token always behaves as if the request were made with Matter-Version: <pinned>. A per-request Matter-Version header overrides for that request only — useful for canary-testing a new version before rotating the token's pinned version.

See /api/conventions/versioning for the monthly release cadence.

Errors specific to the agent surface

All errors follow RFC 7807 (application/problem+json). See /api/conventions/errors for the common envelope.

FAQ

Related

• /api/get-started#authentication — how Bearer auth and version pinning work for all credentials, not just agent tokens.
• /api/auth/tokens — the Token resource shape, generated from the spec.
• /api/authorizations/index — the Authorization resource and its endpoints (approve, deny, retrieve).
• /api/conventions/test-mode — sk_test_ keys, X-Matter-Test-Speed, TestClock, and the test-mode key hierarchy.
• /api/conventions/errors — RFC 7807 error envelope used by every agent-surface error code above.
• /api/conventions/idempotency — how Idempotency-Key is held across a paused authorization.
• /api/conventions/observability — how authorized_by surfaces in logs, traces, and request IDs.
• /api/events/webhooks — HMAC-SHA256 signing, per-entity ordering, and the dual-attribution payload.
• /mcp/introduction — the MCP server, generated from the OpenAPI spec.
• /mcp/authentication — OAuth 2.1 + PKCE for human-user agent clients.
• /mcp/scope-policies — step-by-step authoring guide for the policy DSL with tier-transition examples and a decision tree.