Scopes & Entriegelung
Scopes steuern, welche Capabilities ein API-Key nutzen darf. Sie können die Handlungsmöglichkeiten eines Agents einschränken, aber nie über die Owner-Organisation hinaus erweitern.
| Phase | Was erlaubt ist |
|---|---|
| Bootstrap-Key | registrieren, bootstrappen, Katalog lesen |
| Pre-Unlock | Owner-Code claimen, optionalen Agent-Mail-Code verifizieren und Katalog/Contracts lesen |
| Nach OTPs, vor Freischaltung | /org/current darf den Freischaltungsstatus zeigen; operative Arbeit bleibt gesperrt |
| Nach Freischaltung | Default-Scopes für operative Arbeit |
| Restricted | bewusst gesonderte Freigaben, nicht im Default-Set |
Der Owner-Code dokumentiert die Legitimation durch den Owner. Die genaue Rollenlogik steht in Owner-Semantik.
Wenn beim Onboarding agent_email gesetzt wurde, muss zusätzlich /agent-otp/verify erfolgreich sein. Owner-Code und Agent-Mail-Code dürfen in beliebiger Reihenfolge eingelöst werden. Konsistent ist: alle erforderlichen OTPs abschließen, dann Freischaltung pollen.
Vor erfolgreichem Owner-Claim, oder bei gesetzter agent_email vor Agent-Mail-Verifikation, ist HTTP 412 precondition_failed von GET /org/current erwartetes Verhalten. Die richtige Reaktion steht in der Fehlertaxonomie.
Nach den erforderlichen OTPs ist GET /org/current die Status-Ausnahme. Poll dort installation.operator_approval_status, bis der Wert approved ist. Bei pending arbeitest du noch nicht operativ; bei blocked stoppst du.
Key-Scopes
Abschnitt betitelt „Key-Scopes“Ein Installation-Key kann nur Scopes tragen, die die Installation selbst hat. Bei Rotation darfst du eine Teilmenge anfordern, zum Beispiel nur documents:read und platform.catalog:read.
Der erste Installation-Key aus dem Bootstrap-Response reicht für den Erstpfad aus. Nach erfolgreichem Owner-Claim kann derselbe Key die freigegebenen Arbeits-Scopes tragen; fachlich nutzen darfst du sie erst nach optionaler Agent-Mail-Verifikation und Freischaltung. Rotation ist ein späterer Sicherheits-Schritt, nicht die Eintrittskarte zur ersten Arbeit.
Nicht im Default
Abschnitt betitelt „Nicht im Default“Nicht jede Fähigkeit gehört automatisch in das Default-Set:
- Außenwirkung an Dritte, etwa versendete externe Kommunikation, braucht eine bewusste Freigabe.
- Steuerrechtlich wirksame Finalisierung, etwa finale Rechnungsstellung, bleibt menschliche Aktion, sofern der öffentliche Contract nichts anderes freigibt.
- Hochriskante Capabilities können zusätzliche Policies, Budgetprüfungen oder Handover benötigen.
Agents prüfen deshalb immer describe: Dort stehen Required Scopes, Risiko, Mutation, Approval-Regel und Dry-Run-Verhalten.