Erstelle eine API

POST /v1/apis · Berechtigung apis:write

Erstellt eine API in der Umgebung. key, identifier und name sind erforderlich; ausgelassene optionale Felder erhalten ihre Standardwerte. Der Identifier ist eindeutig in der Umgebung (eine gelöschte API behält ihren Identifier für 90 Tage reserviert). Die Antwort enthält ein ETag mit der aktuellen Version. Sende einen Idempotency-Key-Header, um Wiederholungen sicher zu machen.

Anfrage

Body application/json. Unbekannte Felder werden abgelehnt.

Feld Typ Erforderlich Beschreibung
key string ja Stabiler Konfigurationsschlüssel, ^[a-z0-9_-]{1,64}$. Unveränderbar.
identifier string ja Token-Zielgruppe: eine https-URL (keine Abfrage oder Fragment) oder urn:<nid>:<nss>; in kanonischer Form gespeichert. Unveränderbar. Der Namespace urn:idp: ist reserviert.
name string ja 1–128 Zeichen.
access_token_lifetime_s integer nein 60–86400. Standard 3600 (600 mit mcp_profile).
token_format string nein jwt (Standard) oder opaque.
rbac_mode string nein Wie Rollen und Berechtigungen das Token erreichen: claims (Standard) fügt permissions und org_permissions hinzu; off fügt keines von beiden hinzu (org_roles wird weiterhin hinzugefügt); enforce fügt sie hinzu und begrenzt außerdem die gewährten Scopes auf die effektiven Berechtigungen des Benutzers.
allow_offline_access boolean nein Standard true.
require_resource_indicator boolean nein Standard false (true mit mcp_profile).
dpop_required boolean nein Standard false.
mcp_profile boolean nein Erfordert eine https identifier und require_resource_indicator: true.
first_party_access string nein all (Standard) oder granted_only.
introspection_applications array nein Anwendungen (app_…), die die Token dieser API introspektieren dürfen, höchstens 50, keine Duplikate. Nur web und m2m Anwendungen der gleichen Umgebung. Standardmäßig leer.

Introspektionsanwendungen

Der Introspektions-Endpunkt (POST <issuer>/oauth2/introspect, RFC 7662) antwortet mit active: true für ein Zugriffstoken nur an zwei Aufrufer: die Anwendung, der das Token ausgestellt wurde, oder eine Anwendung in der introspection_applications-Liste der im Token-aud benannten API. Alle anderen Aufrufer erhalten active: false, daher können APIs die Token der anderen nicht lesen. Nur vertrauliche Anwendungen (web, m2m) der gleichen Umgebung können gelistet werden; die Liste wird als Menge gespeichert und in ID-Reihenfolge zurückgegeben. Eine suspendierte Anwendung bleibt auf der Liste, kann aber nicht introspektieren. Die Liste der System-API kann nicht geschrieben werden.

Antwort

201 Created mit einem ETag-Header und der API:

{
  "id": "api_01h455vb4pex5vsknk084sn02q",
  "key": "orders",
  "identifier": "https://api.example.com/orders",
  "name": "Orders API",
  "is_system": false,
  "access_token_lifetime_s": 3600,
  "token_format": "jwt",
  "rbac_mode": "claims",
  "allow_offline_access": true,
  "require_resource_indicator": false,
  "dpop_required": false,
  "mcp_profile": false,
  "first_party_access": "all",
  "introspection_applications": ["app_01h455vb4pex5vsknk084sn02r"],
  "created_at": "2026-10-05T12:00:00Z",
  "updated_at": "2026-10-05T12:00:00Z"
}

Fehler

HTTP Code Wann
400 unknown_field Der Body enthält ein Feld, das oben nicht aufgeführt ist (z. B. id oder is_system).
409 conflict Eine API mit diesem key oder identifier existiert bereits.
415 unsupported_media_type Der Content-Type ist nicht application/json.
422 validation_failed Ein Feld fehlt oder ist ungültig (errors[].pointer, z. B. /identifier).
422 validation_failed Ein introspection_applications-Element existiert nicht in dieser Umgebung (unknown_application), ist nicht vertraulich (not_confidential), ist ein Duplikat (duplicate) oder ist keine app_…-ID (invalid_value); der Zeiger benennt den Index in der Anfrage.
403 quota_exceeded Die Umgebung hat ihre technische API-Grenze erreicht.
403 insufficient_permissions Die Anmeldedaten haben nicht die erforderliche apis:write-Berechtigung.

Beispiel

curl -X POST https://api.eu.keenauth.com/v1/apis \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"key":"orders","identifier":"https://api.example.com/orders","name":"Orders API"}'