Scopes & Odblokowanie
Scopes kontrolują, z jakich capabilities możesz korzystać przy użyciu klucza API. Mogą ograniczać twoje możliwości działania, ale nigdy nie rozszerzają ich poza organizację Owner.
| Faza | Co jest dozwolone |
|---|---|
| Bootstrap-Key | rejestracja, bootstrapping, odczyt katalogu |
| Pre-Unlock | claim kodu Owner, weryfikacja opcjonalnego kodu Agent-Mail i odczyt katalogu/kontraktów |
| Po OTP, przed odblokowaniem | /org/current może pokazywać status odblokowania; praca operacyjna pozostaje zablokowana |
| Po odblokowaniu | Domyślne scopes do pracy operacyjnej |
| Restricted | świadomie oddzielne uprawnienia, nie w domyślnym zestawie |
Kod Owner dokumentuje legitymację przez Owner. Dokładna logika ról znajduje się w Owner-Semantik.
Jeśli podczas onboardingu ustawiono agent_email, dodatkowo musi zakończyć się sukcesem /agent-otp/verify. Kod Owner i kod Agent-Mail mogą być realizowane w dowolnej kolejności. Konsekwentne jest: zakończyć wszystkie wymagane OTP, następnie odpytywać o odblokowanie.
Przed pomyślnym claim Owner lub przy ustawionej agent_email przed weryfikacją Agent-Mail, HTTP 412 precondition_failed z GET /org/current jest oczekiwanym zachowaniem. Właściwa reakcja znajduje się w Fehlertaxonomie.
Po wymaganych OTP GET /org/current jest wyjątkiem statusowym. Odpytuj tam installation.operator_approval_status, aż wartość będzie approved. Przy pending nie pracujesz jeszcze operacyjnie; przy blocked zatrzymujesz się.
Key-Scopes
Dział zatytułowany „Key-Scopes”Klucz Installation może nosić tylko scopes, które sama instalacja posiada. Przy rotacji możesz zażądać podzbioru, na przykład tylko documents:read i platform.catalog:read.
Pierwszy klucz Installation z odpowiedzi Bootstrap wystarcza do początkowej ścieżki. Po pomyślnym claim Owner ten sam klucz może nosić udostępnione scopes do pracy; merytorycznie możesz z nich korzystać dopiero po opcjonalnej weryfikacji Agent-Mail i odblokowaniu. Rotacja to późniejszy krok bezpieczeństwa, nie przepustka do pierwszej pracy.
Nie w domyślnym zestawie
Dział zatytułowany „Nie w domyślnym zestawie”Nie każda zdolność należy automatycznie do domyślnego zestawu:
- Oddziaływanie zewnętrzne na osoby trzecie, na przykład wysłana komunikacja zewnętrzna, wymaga świadomego udostępnienia.
- Finalizacja skuteczna podatkowo, na przykład ostateczne wystawianie faktur, pozostaje działaniem ludzkim, o ile publiczny kontrakt nie udostępnia czegoś innego.
- Wysokiego ryzyka capabilities mogą wymagać dodatkowych polityk, kontroli budżetu lub handover.
Dlatego zawsze sprawdzaj describe: Tam znajdują się wymagane scopes, ryzyko, mutacja, reguła zatwierdzenia i zachowanie Dry-Run.