Authentifizierung: API-Schlüssel und Konten
Wie Browserberg Maschinenschlüssel von menschlichen Dashboard-Konten trennt, wie du einen Bearer-Schlüssel anlegst und den Fehlerumschlag liest.
Zuletzt aktualisiert:
Zwei Zugangsdaten mit Absicht
Browserberg hält zwei Zugangsdaten bewusst getrennt. API-Schlüssel authentifizieren Maschinen: organisationsweite Bearer-Tokens mit dem Präfix bb_, gesendet als Authorization: Bearer bb_... bei jedem API-Aufruf. Dashboard-Konten authentifizieren Menschen: eine httpOnly-Cookie-Sitzung für die Web-App, als API-Zugang nutzlos.
Die Trennung ist nicht kosmetisch. Ein widerrufener, geleakter Schlüssel sperrt nie eine Person aus, eine SSO-Umstellung bricht keine Pipeline, und ein im Log gefundener Schlüssel öffnet nicht das Dashboard. Authentifiziert etwas ein Skript, ist es ein Schlüssel; authentifiziert es eine Person, ist es ein Konto.
Deinen ersten Schlüssel anlegen
-
Dashboard-Konto registrieren
Öffne /app auf deinem Deployment und lege eine Organisation an. Das Konto, mit dem du dich registrierst, wird ihr Owner — und nur ein Owner kann API-Schlüssel anlegen.
-
Die Schlüssel-Ansicht öffnen
Öffne in der Navigation den Bereich "API-Schlüssel" und wähle dort, einen neuen Schlüssel anzulegen.
-
Den Klartext einmal kopieren
Der Schlüssel wird genau einmal angezeigt, direkt beim Anlegen. Kopiere ihn jetzt; er lässt sich nicht erneut anzeigen, nur widerrufen und ersetzen.
-
Als Umgebungsvariable speichern
Exportiere ihn als BROWSERBERG_API_KEY; jedes Beispiel in dieser Doku und beide SDKs lesen ihn standardmäßig. Halte ihn aus der Versionskontrolle heraus.
Der Umschlag, provoziert
Die Fehlerform lernst du am schnellsten, indem du dir eine Ablehnung verdienst. Dieser Request trägt gar keinen Schlüssel:
# A request with no key is refused with the machine-readable envelope every
# error uses. Branch on error.retryable, not on the code: the enum is open.
curl -s -X POST "https://browserberg.com/v1/sessions" \
-H 'Content-Type: application/json' -d '{}' \
| python3 -m json.tool{
"error": {
"code": "unauthorized",
"message": "Provide an API key as `Authorization: Bearer <key>`.",
"retryable": false,
"requestId": "req_xxxxxxxx"
}
}Den Fehlerumschlag lesen
Jede Ablehnung, vom fehlenden Schlüssel bis zur vollen Flotte, kommt im selben Umschlag an: ein error-Objekt mit code, message, retryable und manchmal retryAfterMs, requestId und details. Verzweige auf retryable, nie auf den Code — das Code-Enum ist offen, und ein neuerer Server kann Codes einführen, die dein Switch-Statement nie gesehen hat. retryable: true heißt: warte kurz und versuch es erneut; false heißt: repariere den Request.
Die requestId ist deine Brücke zum Support: Sie benennt den exakten Request in unseren Logs. Nenn sie, wann immer sich etwas anders verhält, als diese Doku vorhersagt.
Tipp · Verbrauch lesen
`GET /v1/usage` liefert die vier gemessenen Dimensionen über ein Fenster, pro Tag, mit offenen Sessions und dem enthaltenen Kontingent; die Ansicht Verbrauch im Dashboard zeichnet es. Siehe die [Anleitung zur Nutzung](/de/docs/anleitungen/nutzung-und-abrechnung).