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.

Ein Client, der keinen Scope anfordert, erhält nur mcp, also Zugriff auf die KI-Werkzeuge von Flexie, nicht auf die REST API. Der Scope api wird niemals stillschweigend mitgegeben.

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", error="invalid_token"

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 Token gilt für genau eine Ressource

Der OAuth-Server von Flexie schützt zwei Dinge: die REST API (api) und den MCP-Server für KI-Agenten (mcp). Ein Client darf beide Scopes haben. Ein Token nicht. Jedes Token ist an eine der beiden Ressourcen 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.

Ein Client mit beiden Scopes fordert deshalb pro Ressource ein Token an und benennt mit dem Parameter resource (RFC 8707), welche gemeint ist:

POST /oauth2/token
  ...&scope=api mcp&resource=api      -> ein Token, das die REST API annimmt
  ...&scope=api mcp&resource=mcp      -> ein Token, das der MCP-Server annimmt

Fordern Sie beide Scopes an, ohne eine Ressource zu benennen, bekommen Sie ein Token, das keiner von beiden annimmt. Es gibt keinen sinnvollen Weg, das für Sie zu entscheiden, deshalb bindet der Server es an nichts, statt zu raten, und beide Ressourcenserver weisen es ab. Wird ein frisch ausgestelltes Token überall abgewiesen, ist das der Grund: Ergänzen Sie resource.

Ein Wert, den der Server nicht kennt, oder einer, der einen nicht gewährten Scope benennt, wird genauso ignoriert; auch resource=https://example.com endet also in einem Token, das an nichts gebunden ist.

Ein Service-Token-Client ist die Ausnahme, und das wird erzwungen. Sein Token wird im Moment des Speicherns erzeugt, ohne Anfrage, die eine resource mitführen könnte, deshalb verlangt das Formular genau einen Scope. Haken Sie beide an, lässt es sich nicht speichern. Wollen Sie Maschine-zu-Maschine-Zugriff auf beides, legen Sie pro Ressource einen Service-Token-Client an.