Authentifizierung und Migration der Verwaltungs-API

Version und API-Adresse

Diese Seite gilt für new-api v1.0.0-rc.44, geprüft am 2026-10-15. Verwaltungsanfragen gehen an https://api.beeaicloud.com. Die Dokumentationsdomain ist keine API-Adresse. Natives /api/, BeeBridge /management-api/ und /integration-api/ haben unterschiedliche Verträge, Sitzungen und Fehlerformate.

Drei verschiedene Zugangsdaten

Ein Sitzungs-access_token ist ein kurzlebiges Bearer-Zugangsmittel aus Passwort- oder OAuth-Anmeldung für Sitzungs- und PAT-Verwaltung. Ein Verwaltungs-PAT beginnt mit nap_, gewährt nur ausgewählte Verwaltungsrechte und kann keine PATs erstellen oder verwalten. Ein Modell-API-Schlüssel dient Inferenzrouten wie /v1/. Derselbe Authorization-Header macht diese Zugangsdaten nicht austauschbar. New-Api-User wählt kein anderes Konto aus; der Server ermittelt die Identität aus den Zugangsdaten.

Anmeldung und Passwortverschlüsselung

Zuerst GET /api/user/login/encryption-key aufrufen. Bei enabled=true werden für Anmeldung und Passwortprüfung password_encrypted und encryption_key_id mit dem zurückgegebenen kid gesendet. Base64-kodiertes RSA-OAEP/SHA-256 wird unterstützt. Für lange Passwörter kapselt v2 einen neuen 32-Byte-AES-Schlüssel mit RSA-OAEP und Label password-v2. AES-256-GCM verwendet eine 12-Byte-Nonce und AAD password-v2:{kid}; das 16-Byte-Tag wird an den Geheimtext angehängt. Format: v2.{wrappedKeyBase64}.{nonceBase64}.{ciphertextAndTagBase64}. Klartext-password nur bei deaktivierter Verschlüsselung und weiterhin über HTTPS senden.

Nach POST /api/user/login data.require_verification prüfen. Bei true den in data.methods angegebenen Ablauf mit flow_token über /api/user/login/verify oder den eigenen Passkey-Ablauf abschließen und erst dann data.access_token verwenden. Anmeldeprüfung und Vorgangsnachweis über /api/verify sind verschieden. Erneuerung: POST /api/user/auth/refresh mit new_api_refresh-Cookie. Abmeldung: POST /api/user/auth/logout. Origin-Prüfungen für Cookie-Anfragen nicht durch gefälschte Herkunft umgehen.

Zusätzliche Vorgangsprüfung

GET /api/verify/methods?scope=access_token.generate aufrufen und eine Methode mit available=true wählen. Danach method, Vorgangs-scope und strikten context an POST /api/verify senden. data.proof_token einmal über X-Security-Proof mit derselben Identität/Sitzung und denselben Vorgangsdetails verwenden. Passkey und OAuth benötigen eigene interaktive Abläufe; eine Änderung von method reicht nicht.

Verwaltungs-PATs und Berechtigungen

Mit der angemeldeten Sitzung /api/user/access_tokens/catalog abrufen und die benötigten Rechte auswählen. profile:read erlaubt nur das eigene Profil, keine Schlüsselverwaltung, sämtliche Nutzungsabfragen oder Wallet-Aktionen. /api/user/access_tokens/scopes ist ein Bezeichnungswörterbuch, kein Katalog aktuell vergebbarer Rechte. Kontostatus, Rolle und aktuelle Autorisierung begrenzen PATs weiterhin.

Fehler und Wiederholungen

HTTP-Status und success prüfen. Codes können in code oder data.code stehen; HTTP 200 kann einen fachlichen Fehler enthalten. Bei 400 SECURITY_CONTEXT_INVALID den Kontext prüfen, bei 401 Zugangsdaten, bei 403 Sitzungsanforderungen und Berechtigungen. Bei 429 enge Wiederholungen stoppen und Wartezeiten beachten. Geht eine Antwort auf Erstellung, Widerruf oder Änderung verloren, vor erneutem Schreiben den Zustand abgleichen. Nur bereinigte Codes, Zeitstempel und Anfrage-IDs protokollieren, keine Geheimnisse.

Migration alter Aufrufe

Altes GET/POST /api/user/token durch POST /api/user/access_tokens ersetzen. GET /api/user/logout wird POST /api/user/auth/logout. GET /api/verify/status wird durch scope-spezifisches /api/verify/methods ersetzt; Nachweise kommen aus Prüfantworten. GET /api/oauth/state wird POST /api/oauth/state. Ein während der Übergangsfrist weiter gültiges altes PAT erhält den alten Ausstellungsablauf nicht. Die Frist aus data.legacy.retire_at der PAT-Liste lesen. Öffentliche native Registrierung ist am aktuellen Produktionseingang geschlossen.

PAT →