metadata.developersAuthentication.title

Bearer-Token

Der Key steht im Authorization-Header — auf beiden Flächen, ohne weitere Header. Aufrufe ohne gültigen Key antworten 401.

Authorization: Bearer $FUTUREWAY_API_KEY

Keys erstellst und widerrufst du unter Einstellungen → API & CLI. Der Klartext wird genau einmal angezeigt.

Zwei Key-Arten

Ein persönlicher Key handelt als du. Ein Service-Key ist die Maschinen-Identität deiner Organisation und sieht nur, was ihm ausdrücklich freigegeben wurde.

	Persönlicher Key	Service-Key
Präfix	`sk-fw-api-…`	`sk-fw-svc-…`
Handelt als	die Person, der er gehört — dieselben Rechte wie im Browser	die Organisation, ohne Person
Sieht	alles, was du selbst siehst	nur Ressourcen, die ein Admin dem Key freigegeben hat
Scopes	fest: inference, agents:run, knowledge:read	beim Anlegen gewählt, aus der Liste unten
Wer legt ihn an	jedes Mitglied mit Plattform-Platz	Inhaber und Admins
Lebensdauer	endet mit dem Konto; wird beim Ausscheiden widerrufen	überlebt Personalwechsel; endet nur durch Widerruf oder Ablauf

Scopes

Ein Scope öffnet den Zugang zu einer Endpunkt-Familie. Was darin sichtbar ist, entscheiden weiterhin die Berechtigungen der Plattform — ein Scope ist nie ein Recht auf eine bestimmte Ressource.

Scope	Öffnet	Persönlich	Service
inference	Inferenz-API: Chat-Completions, Embeddings, Modellliste.	ja	ja
agents:run	Agenten ausführen (App-API, folgt).	ja	ja
knowledge:read	Wissensbereiche auflisten, Dateien lesen, Suche und Graph-Abfragen (App-API, folgt).	ja	ja
knowledge:write	Dateien in Wissensbereiche hochladen, ersetzen und löschen (folgt).	nein	ja
agents:manage	Agenten anlegen und ändern (folgt).	nein	ja
prompts	Prompts anlegen, ändern und löschen (folgt).	nein	ja
usage:export	Aggregierte Nutzungsdaten exportieren — nie Chat-Inhalte (folgt).	nein	ja
audit:read	Audit-Log und Nutzungsprotokoll der Organisation lesen (folgt).	nein	ja
members:invite	Mitglieder einladen und deaktivieren (folgt).	nein	ja

Scopes werden beim Anlegen festgelegt und lassen sich nur verengen. Mehr Rechte bedeuten einen neuen Key. Fehlt der Scope eines Endpunkts, antwortet die App-API 403 scope_missing.

Ein Service-Key erscheint im Freigabe-Dialog jeder teilbaren Ressource (Agenten, Wissensbereiche, Prompts) als eigener Empfänger — neben Gruppen und Mitgliedern, sichtbar nur für Inhaber und Admins. Erst mit einer Freigabe darf der Key die Ressource über die API sehen oder nutzen; ein Widerruf des Keys löscht seine Freigaben.

Ablauf, Rotation, Widerruf

Ablauf beim Anlegen: 30 · 90 · 365 Tage — oder kein Ablauf
Abgelaufener Key: 401 key_expired
Rotation: erzeugt ein neues Secret für denselben Key-Eintrag; Scopes und Ablaufdatum bleiben, der alte Klartext ist sofort ungültig.
Widerrufener Key: 401 unauthorized

Sicherheitsregeln

Nur Server-zu-Server: Die API ist nicht für Aufrufe aus Webseiten oder Apps auf Endgeräten gedacht.
Keys leben in Umgebungsvariablen oder einem Secret-Store — nie im Quellcode, nie in Logs.
Anfragen mit Origin-Header, Fetch-Metadaten oder Session-Cookie werden mit 403 abgewiesen.
Ein Key pro Anwendung und Umgebung, mit den wenigsten Scopes, die sie braucht.

So sieht die Abweisung einer Browser-Anfrage aus:

{
  "error": {
    "code": "browser_request_rejected",
    "message": "The App-API accepts server-to-server requests with an API key only.",
    "request_id": "3f6c1c9e-0a4b-4c3e-9b0e-6a1d2f8e4b21"
  }
}