API-Schlüssel

Ein API-Schlüssel berechtigt ein externes System, zum Beispiel Ihr ERP, die REST API v1 von exoCortex zu nutzen: Tickets eröffnen, ihren Status lesen und Kommentare hinzufügen. Jeder Schlüssel gehört zu einem Tenant und sieht nur die Tickets dieses Tenants.

Einen Schlüssel erstellen

1. Öffnen Sie in exoCortex Core Integrations → API keys. Sie benötigen eine administrative Rolle, zum Beispiel it_admin oder integration_admin.
2. Geben Sie dem Schlüssel einen Namen, der sagt, wer ihn verwendet, zum Beispiel „ERP-Konnektor“.
3. Wählen Sie die Scopes, also was der Schlüssel tun darf (siehe unten).
4. Kopieren Sie den vollständigen Schlüssel und speichern Sie ihn im Secret Manager des Systems, das ihn verwenden wird. exoCortex zeigt ihn nur einmal an und speichert nur einen Fingerabdruck: Wenn Sie ihn verlieren, erstellen Sie einen neuen Schlüssel.

Der Schlüssel hat die Form nhk.<keyid>.<secret>. Die keyid identifiziert den Schlüssel in der Liste; das secret kennen nur Sie.

Scopes

Scope	Was er erlaubt
tickets:create	Tickets eröffnen
tickets:read	Den Status eines Tickets lesen
tickets:comment	Kommentare zu einem Ticket hinzufügen
tickets:*	Alle Operationen auf Tickets
*	Alles, was die API v1 erlaubt

Weisen Sie jedem Schlüssel nur die Scopes zu, die er braucht. Ein Schlüssel ohne Scopes hat vollen Zugriff auf die API v1: Das ist zulässig, aber nicht empfohlen.

Den Schlüssel verwenden

Senden Sie den Schlüssel im Header Authorization jeder Anfrage:

POST /api/v1/tickets HTTP/1.1
Host: exocortex-api.ai-exo-cortex.com
Authorization: Bearer nhk.9f2c4e1a7b3d.…
Content-Type: application/json
Idempotency-Key: 6b1f0c4e-2a7d-4b39-9e51-8c3d2f7a1b60

{ "subject": "Payment gateway returns HTTP 502", "priority": "High" }

Alternativ können Sie den Header X-NH-API-Key verwenden. Den Tenant geben Sie nicht an: exoCortex leitet ihn aus dem Schlüssel ab.

Verwenden Sie beim Eröffnen eines Tickets immer Idempotency-Key: Wenn Sie die Anfrage mit demselben Idempotenzschlüssel wiederholen, erhalten Sie das bereits erstellte Ticket statt eines Duplikats.

Ratenlimits

Jeder Schlüssel hat ein Anfragelimit: Der Standardwert ist 600 Anfragen pro 60 Sekunden. Jede Antwort zeigt Ihren aktuellen Stand:

Header	Bedeutung
RateLimit-Limit	Im Zeitfenster zulässige Anfragen
RateLimit-Remaining	Noch verfügbare Anfragen
RateLimit-Reset	Sekunden bis zum neuen Zeitfenster
Retry-After	Nur bei der Antwort 429: Sekunden, die Sie vor einem neuen Versuch warten müssen

Fehler

Fehler der API v1 liefern ein JSON mit ok: false, einer lesbaren Meldung in error und einem stabilen Code in code. Bauen Sie die Logik Ihres Clients auf code auf, nicht auf der Meldung.

code	HTTP-Status	Was zu tun ist
missing_api_key	401	Fügen Sie den Header Authorization hinzu
invalid_api_key	401	Prüfen Sie den Schlüssel: Er kann falsch oder widerrufen sein
insufficient_scope	403	Fügen Sie dem Schlüssel den in required_scope angegebenen Scope hinzu
api_key_disabled	403	Der Schlüssel ist deaktiviert: Verwenden Sie einen aktiven Schlüssel
validation_error	400	Korrigieren Sie das in field angegebene Feld
not_found	404	Das Ticket existiert nicht oder gehört nicht zum Tenant des Schlüssels
rate_limited	429	Warten Sie die in Retry-After angegebenen Sekunden ab
ingest_failed	500	Wiederholen Sie die Anfrage mit demselben Idempotency-Key

exoCortex kann neue Codes hinzufügen: Wenn Sie einen unbekannten Code erhalten, entscheiden Sie anhand des HTTP-Status.

Einen Schlüssel widerrufen

Unter Integrations → API keys widerrufen Sie einen Schlüssel, wenn ein System ihn nicht mehr verwendet oder wenn Sie vermuten, dass er offengelegt wurde. Der Widerruf gilt sofort. Die Liste zeigt außerdem die letzte Verwendung jedes Schlüssels: So finden Sie inaktive Schlüssel.

Veraltete Schlüssel nh_…

Schlüssel im alten Format nh_… funktionieren bis zum 30. Juni 2027. Antworten auf diese Schlüssel enthalten die Header Deprecation und Sunset. Zur Migration erstellen Sie einen nhk.-Schlüssel mit den nötigen Scopes, aktualisieren das System, das ihn verwendet, und widerrufen dann den alten Schlüssel.