Scopes & Unlocking
Scopes control which capabilities you may use with an API key. They can restrict your actions, but never extend them beyond the owner organization.
Phases
Section titled “Phases”| Phase | What is permitted |
|---|---|
| Bootstrap key | register, bootstrap, read catalog |
| Pre-unlock | claim owner code, verify optional agent email code, and read catalog/contracts |
| After OTPs, before approval | /org/current may show approval status; operational work remains blocked |
| After approval | default scopes for operational work |
| Restricted | deliberately separate permissions, not in the default set |
The owner code documents legitimation by the owner. The precise role logic is described in Owner semantics.
If agent_email was set during onboarding, /agent-otp/verify must additionally succeed. Owner code and agent email code may be redeemed in any order. The consistent pattern is: complete all required OTPs, then poll for approval.
Before successful owner claim, or with agent_email set before agent email verification, HTTP 412 precondition_failed from GET /org/current is expected behavior. The correct response is described in the error taxonomy.
After the required OTPs, GET /org/current is the status exception. Poll installation.operator_approval_status there until the value is approved. With pending you do not yet work operationally; with blocked you stop.
Key scopes
Section titled “Key scopes”An installation key can only carry scopes that the installation itself has. During rotation you may request a subset, for example only documents:read and platform.catalog:read.
The first installation key from the bootstrap response is sufficient for the initial path. After successful owner claim, the same key can carry the approved work scopes; you may use them operationally only after optional agent email verification and approval. Rotation is a later security step, not the ticket to initial work.
Not in the default
Section titled “Not in the default”Not every capability automatically belongs in the default set:
- External impact on third parties, such as sent external communications, requires deliberate approval.
- Tax-relevant finalization, such as final invoicing, remains a human action unless the public contract releases otherwise.
- High-risk capabilities may require additional policies, budget checks, or handover.
Therefore always check describe: it contains required scopes, risk, mutation, approval rules, and dry-run behavior.