Authentifizierung

Jede API-Anfrage handelt als Benutzer. Was diese Person sehen und ändern darf, darf die Anfrage sehen und ändern, mehr nicht. Ihr Name erscheint in der Historie von allem, was die Anfrage berührt.

Es gibt zwei Wege nachzuweisen, wer Sie sind.

Die zwei Zugangsberechtigungen

	API-Schlüssel	OAuth
Sieht aus wie	`apikey: tCgjfl…`	`Authorization: Bearer …`
Einer pro	Benutzer	Benutzer / Integration
Läuft ab	nie	je nach Typ
Eine einzelne Integration entziehen	nicht möglich, ein Schlüssel bedient alle	ja, unabhängig voneinander
Von Flexie gespeichert als	der Schlüssel selbst	ein Fingerabdruck des Tokens
Am besten für	ein schnelles Skript, eine erste Integration	alles, was bleiben soll

Beide werden an jedem Endpunkt angenommen. Sie müssen sich nicht vorab entscheiden: Ein Arbeitsbereich kann mit dem Schlüssel beginnen und später auf OAuth wechseln, pro Benutzer, ohne Stichtag.

Den API-Schlüssel verwenden

Senden Sie ihn im apikey-Header:

curl "https://ihre-subdomain.flexie.io/api/leads?limit=5" \
  -H "apikey: IHR_API_SCHLUESSEL"

Oder als Query-Parameter, praktisch für einen schnellen Test im Browser:

curl "https://ihre-subdomain.flexie.io/api/leads?limit=5&apikey=IHR_API_SCHLUESSEL"

Der Header heißt apikey, klein geschrieben, ein Wort. X-Api-Key, Api-Key und ApiKey werden nicht erkannt.

Wo Sie ihn finden: Öffnen Sie den Benutzer unter Einstellungen → Benutzer und dann den Reiter API-Einstellungen. Dort wird der Schlüssel angezeigt und kann neu erzeugt werden. Das Neuerzeugen wird wirksam, sobald Sie auf Aktualisieren klicken, und es bricht in diesem Moment jede Integration, die den alten Schlüssel nutzt, denn ein Benutzer hat genau einen Schlüssel.

Senden Sie keinen Authorization-Header zusammen mit einem API-Schlüssel. Eine Anfrage mit Authorization: Bearer … gilt als OAuth-Anfrage, und Ihr Schlüssel wird gar nicht erst herangezogen. Senden Sie das eine oder das andere, niemals beides.

OAuth verwenden

OAuth vergibt pro Integration eine eigene Zugangsberechtigung. So können Sie eine abschalten, ohne die anderen anzufassen, und Sie sehen, welche Integration was getan hat.

Für eine serverseitige Integration

Das ist es, was die meisten Integrationen wollen: kein Browser, kein Anmeldebildschirm, ein langlebiges Token.

Öffnen Sie unter Einstellungen → Benutzer den Benutzer, als der die Integration handeln soll
Wechseln Sie auf den Reiter API-Einstellungen
Klicken Sie auf API-Client hinzufügen, benennen Sie ihn nach der Integration und speichern Sie
Kopieren Sie das Token, es wird einmalig angezeigt

Senden Sie es dann als Bearer-Token:

curl "https://ihre-subdomain.flexie.io/api/leads?limit=5" \
  -H "Authorization: Bearer IHR_TOKEN"

Alles andere an der Anfrage ist identisch. Dieselben Pfade, dieselben Rümpfe, dieselben Antworten.

Für eine App, die viele Menschen nutzen

Eine App, die im Namen der jeweils angemeldeten Person handelt, verwendet den üblichen Authorization-Code-Flow gegen den OAuth-Server Ihres Arbeitsbereichs. Sie muss den Scope api ausdrücklich anfordern:

GET https://ihre-subdomain.flexie.io/oauth2/authorize
      ?response_type=code
      &client_id=IHRE_CLIENT_ID
      &redirect_uri=https://ihreapp.example.com/callback
      &scope=api
      &state=ZUFALL
      &code_challenge=…&code_challenge_method=S256

PKCE mit S256 ist Pflicht. Tauschen Sie den Code wie gewohnt unter POST /oauth2/token ein.

Benennen Sie den Scope. Eine Anfrage ohne Scope wird abgewiesen, und api wird niemals stillschweigend mitgegeben:

{ "error": "invalid_scope", "error_description": "A scope is required." }

Client-Zugangsdaten vergibt eine Administratorin unter Einstellungen → OAuth-Clients. Einen Endpunkt zur Selbstregistrierung gibt es nicht: Für eine Aufruferin, die Flexie nicht identifiziert hat, wird kein Client-Datensatz geschrieben. Eine App, die an viele Arbeitsbereiche ausgeliefert wird, kann stattdessen ein Client ID Metadata Document veröffentlichen und dessen URL als client_id verwenden. Der Datensatz entsteht dann in dem Moment, in dem jemand sie auf dem Zustimmungsbildschirm bestätigt.

Discovery

Die REST API veröffentlicht ihre eigenen Metadaten nach RFC 9728:

curl "https://ihre-subdomain.flexie.io/.well-known/oauth-protected-resource/api"

{ "resource": "https://ihre-subdomain.flexie.io/api",
  "authorization_servers": ["https://ihre-subdomain.flexie.io"],
  "scopes_supported": ["api"],
  "bearer_methods_supported": ["header"] }

Das Dokument unter dem blanken Pfad /.well-known/oauth-protected-resource beschreibt stattdessen den MCP-Server. Folgen Sie dem, auf das der WWW-Authenticate-Header verweist.

Einen Benutzer vom Schlüssel auf OAuth umstellen

Die beiden Zugangsberechtigungen schließen sich pro Benutzer bewusst gegenseitig aus, damit es nie einen Moment gibt, in dem beide funktionieren und Sie nicht sagen können, welche eine Integration gerade nutzt.

Sobald ein Benutzer einen aktiven API-Client hat, funktioniert sein API-Schlüssel nicht mehr. Die nächste per Schlüssel authentifizierte Anfrage erhält:

{ "error": "api_key_disabled",
  "error_description": "This API key is disabled because an active OAuth client with the api scope exists for this user. Authenticate with OAuth instead, or deactivate that client to re-enable the key." }

Der Weg zurück ist ein Klick. Schalten Sie den Client auf dem Reiter API-Einstellungen dieses Benutzers ab oder löschen Sie ihn, und der Schlüssel funktioniert schon bei der nächsten Anfrage wieder. Nichts geht verloren, und kein anderer Benutzer ist betroffen: Die Umstellung gilt pro Person und wird von den Clients eben dieser Person ausgelöst.

Eine sinnvolle Migration sieht deshalb so aus: den Client anlegen, die Integration umziehen, prüfen, dass sie läuft. Geht etwas schief, schalten Sie den Client ab und Ihr alter Schlüssel ist wieder aktiv, während Sie der Sache nachgehen.

Die Berechtigung, die API überhaupt zu nutzen

Unabhängig davon, welche Zugangsberechtigung Sie haben, entscheidet die Rolle eines Benutzers, ob er die REST API nutzen darf. Setzen Sie unter Einstellungen → Rollen bei API-Berechtigungen den Haken bei Zugriff auf REST API.

Ein Benutzer, dessen Rolle das nicht gewährt, wird abgewiesen, welche Zugangsberechtigung er auch vorlegt:

{ "error": "access_denied",
  "error_description": "This account does not have REST API access. Ask an administrator to enable Access REST API for its role." }

Diese Ablehnung ist ein 403, kein 401, denn eine andere Zugangsberechtigung hilft hier nicht weiter. Administratoren kommen immer durch.

Jede Ablehnung und was zu tun ist

Status	`error`	Was passiert ist	Was zu tun ist
401	`invalid_grant`	Der API-Schlüssel fehlt oder ist unbekannt	Schreibweise des `apikey`-Headers und den Schlüssel selbst prüfen
401	`api_key_disabled`	Der Schlüssel ist gültig, dieser Benutzer hat aber einen aktiven API-Client	OAuth verwenden oder diesen Client abschalten
401	`invalid_token`	Das Bearer-Token ist unbekannt, abgelaufen, entzogen, gehört zu einem inaktiven Client oder wurde für eine andere Ressource ausgestellt	Ein frisches Token holen; wurde es für MCP ausgestellt, wird es hier nie funktionieren
403	`access_denied`	Die Rolle des Benutzers gewährt keinen Zugriff auf die REST API	In der Rolle aktivieren
404	keiner	Die Anfrage hat die API nie erreicht	Siehe unten

Die OAuth-Ablehnungen führen einen WWW-Authenticate-Header mit, der auf das Discovery-Dokument zeigt, sodass ein standardkonformer Client den Ablauf selbstständig neu starten kann:

WWW-Authenticate: Bearer resource_metadata="https://ihre-subdomain.flexie.io/.well-known/oauth-protected-resource/api", scope="api", error="invalid_token"

Er benennt neben dem Dokument auch den Scope, sodass einem Client gesagt wird, was er anfordern soll, statt dass er es sich erschließen muss.

Ein 404 auf einem Pfad, den es nachweislich gibt, heißt meist, dass gar keine Zugangsberechtigung mitgesendet wurde. Anfragen an /api laufen über einen Proxy, der entweder einen apikey- oder einen Authorization: Bearer-Header erwartet und alles andere abweist, bevor Flexie es überhaupt sieht. Liefert ein Aufruf 404 und eine HTML-Seite statt JSON, prüfen Sie, ob Ihre Zugangsberechtigung tatsächlich mitgeht: Manche HTTP-Clients verwerfen eigene Header bei einer Weiterleitung.

Ein Client, eine Ressource

Der OAuth-Server von Flexie schützt zwei Dinge: die REST API (api) und den MCP-Server für KI-Agenten (mcp). Jedes Token ist an eine der beiden gebunden, und die andere weist es ab.

Das ist der Punkt, auf den es ankommt, denn genau das verhindert, dass ein Token, das Sie einem KI-Agenten geben, umgedreht und über die REST API gegen Ihre Datensätze verwendet wird.

Der Scope gehört deshalb zum Client, wird einmal beim Anlegen gewählt, und es ist genau eine Wahl. Ein Client ist entweder ein REST-API-Client oder ein MCP-Client. Brauchen Sie beides, legen Sie zwei Clients an; das ist zugleich, was Ihnen erlaubt, den einen abzuschalten, ohne den anderen anzufassen.

Eine Anfrage, die beide benennt, wird abgewiesen, statt ein Token auszustellen, das niemand annimmt:

{ "error": "invalid_scope",
  "error_description": "A token is issued for a single resource, so ask for one of mcp or api per request, not both." }

Und eine Anfrage nach einem Scope, den ihr Client nicht hat, wird genauso abgewiesen:

{ "error": "invalid_scope", "error_description": "Client is not authorised for scope: api" }

Wenn Ihr Client `resource` statt `scope` sendet

MCP-Clients folgen RFC 8707 und senden eine resource statt eines Scopes. Das funktioniert hier: Eine Ressource benennt genau eine der beiden, es gibt also nichts zu raten.

&resource=api      -> dasselbe wie &scope=api

Eine resource, die der Server nicht kennt, wird ignoriert. Bleibt die Anfrage dadurch ganz ohne Scope, wird sie mit A scope is required. abgewiesen, statt etwas Unbrauchbares auszustellen. resource=https://example.com allein scheitert also sofort, statt ein Token zu erzeugen, das niemand annimmt.