Identity & scopes
Every call to Forge carries an identity, and every identity carries a set of scopes — named powers, checked by the kernel.
The three kinds of caller
Section titled “The three kinds of caller”- A shopper. Anonymous or signed in. Reaches the public read face and the public commands of the purchase journey. Buying is not an operator power; a shopper does it with no credential at all.
- An operator. A person on your staff, signed into the admin. Their scopes come from their role.
- A service. An API key — an integration, a script, an agent.
The key is the actor
Section titled “The key is the actor”This is the part that surprises people, and it is the most useful property in the system.
When you create an API key you name it — ERP Nimbus, BI panel, Warehouse sync. That name is not a
label on a credential belonging to a person. The key is its own actor, and the audit trail records it by
name on every call, including the refusals.
So “who changed this price?” has an answer that is a thing rather than a guess, and revoking an integration does not mean disabling a human being.
Scopes
Section titled “Scopes”A scope is a name like catalog.product.write or order.read. The kernel checks it; the caller is never
trusted to check itself.
Three properties worth knowing:
They are the same everywhere. A scope withheld is withheld on the API, the CLI, MCP and the SDK at once, because all four reach the same gate. There is no proxy rule to keep in step.
Nobody grants what they do not hold. Creating a key is fenced subset-of-issuer: you cannot mint a credential more powerful than the one you are minting it with. Privilege cannot be escalated by going one level deeper.
A refusal is named. Reaching past your scopes returns forbidden with the scope named — not a 404, not
an empty list. See errors and refusals.
The full list, with the commands and reads under each, is on the scopes page — generated from the kernel’s own table.
An operator’s scopes come from a role. Roles are editable, and the scopes they carry are the same vocabulary apps ask consent in — one language for “what may this actor do”, whether the actor is a person, a key or an app.
⚠️ Some reads answer any authenticated operator and no role can exclude them — the caller’s own identity, for instance, since gating that would lock everyone out of the shell. Those are listed explicitly on the scopes page rather than being an unstated exception.
Masking
Section titled “Masking”Holding a scope opens a screen. It does not automatically make everything inside it legible.
Personal data comes back masked for an actor without pii.read, with the shape unchanged — your code
sees the same fields, carrying j***@e***.com instead of the address. Two questions, answered separately:
who may open this, and what may they read once inside.
⚠️ The public read face masks even for the party holding the identifier. A guest reading their own checkout gets a masked buyer. Possession of a cart id is not proof of identity, and the front-end that typed the value is the one that should still have it.
Rotation and revocation
Section titled “Rotation and revocation”A key can be rotated: a new credential is minted on the same actor, and the previous ones stay alive for an overlap window. Your integration survives its own redeploy without a flag day, and the audit trail stays continuous because the actor did not change.
Revocation is immediate and kills every generation of the key at once.