REST-API

Authentifizierung

Jede Anfrage an die REST-API trägt einen API-Schlüssel. So legst du ihn an, prüfst ihn und widerrufst ihn.

So funktioniert es

Die API erkennt deinen Workspace am Schlüssel. Du schickst ihn in der Kopfzeile x-api-key mit. Ein Schlüssel beginnt immer mit lymbe_, danach folgen 48 Zeichen.

Kopfzeilehttp

x-api-key: lymbe_DEIN_SCHLUESSEL

Wer darf Schlüssel anlegen?

Nötig ist das Recht API-Schlüssel verwalten. Im Rollen-Editor steht dazu: „Ein Schlüssel öffnet den Zugang zu allen Daten des Workspaces.“ Vergib es daher sparsam (siehe Team und Rollen).
Dein Tarif muss API-Zugang und das Anlegen von Schlüsseln enthalten. Sonst erscheint „API-Zugang ist in Ihrem Plan nicht enthalten. Bitte upgraden.“ bzw. „API-Key-Erstellung ist in Ihrem Plan nicht enthalten. Bitte upgraden.“

Schlüssel anlegen

Öffne Einstellungen → API Keys.
Klicke auf API-Key erstellen.
Gib im Dialog „Neuen API-Key erstellen“ einen Namen des Keys ein, z. B. „Produktionsserver“ oder „CRM-Abgleich“.
Bestätige. Es erscheint „API-Key erstellt!“ mit dem vollständigen Schlüssel.
Klicke auf Kopieren und lege den Schlüssel sofort in deinem Passwort-Manager oder als Umgebungsvariable auf deinem Server ab.
Schließe mit Fertig. Wer schließen will, ohne kopiert zu haben, wird gefragt: Key jetzt kopieren oder Ohne Kopie schließen.

Der Schlüssel wird nur einmal angezeigtLymbe speichert nur einen Hash des Schlüssels. Danach siehst du nur noch die ersten 12 Zeichen. Verlorene Schlüssel kannst du nicht wiederherstellen: Widerrufe sie und lege einen neuen an.

Die Schlüsselliste

Spalte	Bedeutung
Name	Der Name, den du beim Anlegen vergeben hast, und die ersten 12 Zeichen des Schlüssels
Erstellt von	Wer den Schlüssel angelegt hat
Erstellt am	Datum der Erstellung
Zuletzt verwendet	Wann der Schlüssel zuletzt erfolgreich benutzt wurde, sonst „Noch nie“

Schlüssel kannst du auch dann noch sehen und widerrufen, wenn dein Workspace gesperrt ist.

Schlüssel prüfen: GET /verify

Mit /verify testest du, ob ein Schlüssel gilt. Der Endpunkt prüft keinen Tarif und zählt nicht zur Anfragen-Grenze. Er eignet sich daher gut für den Knopf „Verbindung testen“ in deiner eigenen Anwendung.

curlbash

curl https://app.lymbe.ai/api/v1/verify \
  -H "x-api-key: lymbe_DEIN_SCHLUESSEL"

Antwort 200json

{
  "valid": true,
  "tenant": { "name": "Beispiel GmbH", "slug": "beispiel-gmbh" },
  "plan": { "name": "Business" }
}

Antwort 401json

{ "valid": false, "error": "Invalid API key" }

Status	Wann
200	Schlüssel gilt
401	`API key required` (keine Kopfzeile) oder `Invalid API key`
404	`Tenant not found`
429	Zu viele falsche Schlüssel von deiner IP-Adresse (60 in 15 Minuten)

Schlüssel widerrufen

Öffne Einstellungen → API Keys.
Klicke in der Zeile des Schlüssels auf Widerrufen und bestätige.
Ab sofort antwortet die API auf diesen Schlüssel mit 401. Das lässt sich nicht rückgängig machen.

Gute Praxis

Ein Schlüssel je System. Dann kannst du einen einzelnen widerrufen, ohne alle anderen zu stören.
Schlüssel nur auf dem Server, als Umgebungsvariable, nie im Quellcode-Repository und nie im Browser.
Schlüssel regelmäßig tauschen: neuen anlegen, im System eintragen, alten widerrufen.
Spalte „Zuletzt verwendet“ prüfen. Schlüssel, die lange niemand nutzt, widerrufst du.

Fehlerbehebung

Problem	Lösung
`401 API key required`	Die Kopfzeile heißt `x-api-key`. Prüfe, ob dein HTTP-Client sie wirklich mitschickt.
`401 Invalid API key`	Schlüssel unvollständig kopiert, mit Leerzeichen am Ende oder bereits widerrufen.
`403` trotz gültigem Schlüssel	Dein Tarif enthält keinen API-Zugang. `/verify` funktioniert trotzdem, die anderen Endpunkte nicht.
Knopf „API-Key erstellen“ fehlt	Dir fehlt das Recht API-Schlüssel verwalten. Frag den Inhaber deines Workspaces.

Weiter: Überblick · API-Playground · Sicherheit im Workspace

VorherigeÜberblick NächsteGespräche