API
Authentication
Scoped credentials and the four-tier agent model — tokens, agents, and the policy DSL that governs them.
Last updated
TL;DR. Three credential types — secret keys (sk_*, full account scope), publishable
keys (pk_*, read-only on whitelisted endpoints), and scoped tokens (tok_*, four tiers
× a structured policy). Pick the narrowest credential that covers the job; agents almost
always want a scoped token, not a secret key.
Every Matter request authenticates with a key or token. Secret keys (sk_live_, sk_test_)
carry full account scope — treat them as God-mode credentials and store them in a secret
manager. Publishable keys (pk_live_, pk_test_) are read-only on whitelisted endpoints,
safe to ship in browsers and mobile apps. Scoped tokens (tok_) carry one of four tiers —
observe, prepare, execute, autonomous — plus a structured policy that bounds what
the holder can touch at the resource and field level. The tier model maps cleanly onto the
OAuth 2.0 scope concept but with
opinionated tiers so agent code stays portable across customers.
When to use which
Secret key — server-side code you fully control. Publishable key — front-end widgets that read but never mutate. Scoped token — every other case, especially anything an AI agent or third-party integrator touches. If you find yourself reaching for a secret key to give an agent, you almost certainly want a tier-2 or tier-3 scoped token instead.
Tokens
Mint, retrieve, rotate, and revoke scoped credentials. Includes the policy DSL.
Agents
Agent identity, dual-attribution, and the Authorization resource for human-in-the-loop pauses.