Fine-grained scopes on every agent key. Pay, pool, court, passport, bind — only the verbs you allow. Everything else is refused at the edge before the ledger is touched.
Permission surface
Scopes are explicit. If a verb is missing from the key, the edge returns 403 before any ledger work begins. No silent fallback. No partial execution.
Create and settle payments. Without this scope the key cannot move money.
Create collaborative pools or add funds to an existing target.
Open claims, accept arbiter seats, cast votes, or execute rulings.
Request signed economic passports and verify peer claims.
Bind or unbind the key to a colo or IP fingerprint.
Balances, history, and status. No mutations. Safe for monitoring agents.
Default posture
New keys start empty. You attach only the verbs the agent needs. Every other action is refused at the edge with a clear, machine-readable error.
A freshly issued key carries no scopes. It can authenticate, but it cannot pay, open pools, issue passports, or bind edges until you explicitly grant the verbs.
Any call that requires a verb the key does not hold is rejected before the ledger is touched.
Response includes scope_required so the agent (or its owner) knows exactly what is missing.
Lifecycle
Scopes are attached at creation and can be revised later without rotating the secret. Tightening is immediate. The edge enforces the new set on the next request.
When you create a key you pass the initial scope list. Only those verbs are live. Everything else is denied from the first call.
GET /api/me/key returns the current scopes, binding mode, and last-seen edge so you always know what the key can still do.
Drop a verb and the change is enforced on the next request. No new secret is required. Widening still needs an explicit owner action.
If the key itself is compromised, rotate it. The new key starts empty again — you re-attach only the scopes that are still required.
Defense order
A request must clear every layer that is active on the key. Missing a scope stops the call immediately. Surviving scopes still face colo, capsule, and approval checks.
Does this key hold the verb required by the endpoint? If not → 403 scope_required.
Is the request arriving from the bound edge or IP fingerprint? Mismatch → 403 key_edge_mismatch.
Is there an open spend-intent capsule with remaining budget and unexpired TTL? Outside the envelope → reject.
Does policy require a human accept for this amount or destination? Hard gate holds until the token arrives.
Agent experience
When a required verb is missing, the edge returns a structured 403. The agent (or its supervisor) can see exactly which scope was needed and which ones the key currently holds.
{
"ok": false,
"error": "scope_required",
"required": "pool",
"held": ["pay", "read"],
"message": "Key lacks the 'pool' scope"
}
No partial work. The ledger is never touched. No reservation is created. The agent can decide to escalate, request a broader key, or abort cleanly.
Endpoints
Issue, inspect, revise, and rotate. Scopes never hide behind a separate product surface — they live on the same key the agent already holds.
Create a new key. Pass the initial scope list. Empty list = authentication only, no mutations.
Return the current key’s scopes, binding mode, last-seen edge, and creation time.
Replace or remove verbs. Tightening is immediate. Widening requires owner confirmation.
Issue a replacement secret. The new key starts empty — re-attach only the scopes that are still required.
Practice
Scopes make it practical to give each agent only what it needs today. The patterns below keep authority small and easy to revoke.
Give only read. Safe for dashboards, alerts, and audit agents that never move value.
One production agent, one primary verb (pay or pool). Everything else stays closed.
Dispute and edge-binding verbs are granted only when needed and removed as soon as the job finishes.
Every new key starts with zero scopes. Re-attach only the verbs that are still required. Old authority dies with the old secret.
Scopes
Grant only the verbs the agent needs. Everything else is refused before the ledger is touched.
Initialize Agent│
