Authentifizierung und Scopes

Lokale Operationen benötigen ein angemeldetes Desktop-Konto und ein separates Bearer-Token mit den erforderlichen Scopes. Kontofreigaben, Tokenablauf und Widerruf werden unabhängig geprüft.

Pflichtkonto im Desktop

Melde dich im Kontofenster des Desktops an oder registriere dich, bevor du Profile, API, MCP oder Automatisierung nutzt. Ein lokales API-Token ersetzt keine Kontoanmeldung. Die Serverbestätigung gilt lokal höchstens 15 Sekunden; eine abgelaufene Bestätigung oder ein nicht erreichbarer Kontodienst sperrt weitere geschützte Aktionen. Stoppen und Abmelden bleiben möglich.

GET /api/v1/account/status zeigt den Bestätigungszustand ohne Kontozugangsdaten. Kontobindung und Abmeldung gehören zur Manager-Sitzung und sind keine Integrationsschnittstellen. Der lokale Profilbestand wird an das zuerst bestätigte Konto gebunden; ein anderes Konto erhält keinen Zugriff auf diesen Bestand.

403 Code	Bedeutung
account.required / account.revoked / account.unavailable	Erneut anmelden oder Kontoverbindung wiederherstellen.
account.owner_mismatch	Das an diesen lokalen Profilbestand gebundene Konto verwenden.
account.feature_denied / account.limit_reached	Der Kontotarif gibt die Funktion nicht frei oder sein konfiguriertes Limit ist erreicht.

Bearer-Authentifizierung

HTTP

Authorization: Bearer <LOCAL_API_TOKEN>
Content-Type: application/json

Sende den Header bei authentifizierten Anfragen. POST, PUT und PATCH benötigen application/json, auch bei Operationen mit einem leeren JSON-Objekt. Die Tokenerstellung liefert Klartext nur einmal; Tokenlisten liefern Metadaten und einen Hinweis, nicht das ursprüngliche Geheimnis.

Minimale Scopes auswählen

Scope	Zweck
profiles:read	Profile und Profilmetadaten lesen
profiles:write / profiles:delete	Profile erstellen/ändern / Profile löschen
runtime:control	Profile starten/stoppen und Browserseiten bedienen
proxies:read / proxies:write	Proxys lesen/verwalten
cookies:read / cookies:write	Cookies lesen/schreiben; Werte können Kontozugriff ermöglichen
secrets:read / secrets:totp	Geschützte Geheimnisse lesen / TOTP-Werte abrufen
rpa:run / rpa:write	RPA-Abläufe ausführen / konfigurieren
sync:control	Live-Synchronisierung steuern
extensions:write / kernels:manage	Erweiterungen / Browserkerne verwalten
trash:manage / settings:write / audit:read	Papierkorb verwalten / Einstellungen schreiben / Audit lesen
admin	Verwaltungsoperationen einschließlich Tokenverwaltung; erfüllt andere Scope-Prüfungen

Scope-Prüfungen sind nur eine Ebene: Tresorzustand, Ressourcenrechte, Laufzustand und beschreibbarer Speicher können weitere Voraussetzungen setzen. Das OpenAPI-Feld x-required-scopes nennt die festen Routenrechte; alle aufgeführten Scopes sind erforderlich und admin erfüllt diese Prüfungen. Bedingte Prüfungen anhand von Anfrageinhalt oder Ressourcen bleiben zusätzliche Voraussetzungen. Die Tabelle hilft bei der Aufgabenauswahl und behauptet nicht, dass jede Operation einer Familie gleiche Rechte hat. Lies die Details von auth.scope_missing oder prüfe MCP tools/list der installierten App.

Tokenarten und Vorgaben

Tokenarten sind native, compat und mcp. Die MCP-Vorgabe lässt admin, secrets:read und trash:manage aus, enthält aber weiterhin Schreiboperationen und Zugriff auf sensible Seiten-/Cookie-Daten. Die Skriptvorgabe lässt admin, settings:write und secrets:read aus. Full enthält alle Scopes. Wähle im Token-Dialog der Desktop-App „Eigene Rechte“, um einzelne Scopes für Native-API- oder MCP-Tokens auszuwählen. Ausdrückliche scopes ersetzen die Vorgabe; sie werden nicht ergänzt. Tokens der Art mcp können über die Token-API nicht mit admin oder secrets:read erzeugt werden.

POST /api/v1/tokens

{
  "name": "Read-only integration",
  "kind": "native",
  "scopes": [
    "profiles:read"
  ],
  "expires_at": null
}

Dieses administrative Beispiel hat wegen expires_at: null keinen Ablauf. Für ein zeitlich begrenztes Token gib einen Unix-Zeitstempel in Millisekunden in der Zukunft an. Gib der Integration nicht allein zur eigenen Tokenerstellung admin; erzeuge ihr Token in der App mit den benötigten Rechten.

Ablauf, Widerruf und Austausch

Fehlendes oder null gesetztes expires_at bedeutet keinen automatischen Ablauf. Ein Token wird ab Erreichen von expires_at oder nach Widerruf durch DELETE /api/v1/tokens/{id} abgewiesen. Dieses DELETE widerruft den Zugang, nicht die Browserprofile. Zum Austausch: Ersatz erzeugen, Client lokal aktualisieren, Lesezugriff prüfen, dann das vorige Token widerrufen. Tokens gehören nicht in URLs, Screenshots, Repositories oder Supportlogs.