Authentifizierung

Jeder Aufruf der KLA Control Plane API wird mit einem kurzlebigen OAuth-2.0-Bearer-Access-Token authentifiziert und auf einen einzelnen Mandanten beschränkt. Die KLA Control Plane ist eine govern-in-place-Schicht für Laufzeitsicherheit, Auditierung und Governance von KI-Agenten im Unternehmen. Über ihre API registrieren Sie Agenten, werten Richtlinien aus, leiten Genehmigungen weiter und rufen Nachweise ab. Diese Seite erläutert die beiden Anmeldedatentypen, wie Sie ein Token erhalten, wie Sie die API aufrufen und wie Sie Anmeldedaten mit minimalen Rechten ausstatten und rotieren.

Zwei Anmeldedatentypen

KLA stellt Token über seinen Identity Provider aus, einen OpenID-Connect-(OIDC)-Dienst. Welchen Flow Sie verwenden, hängt davon ab, wer den Aufruf tätigt.

Die interaktive Anmeldung ist das, was die Console verwendet. Der Browser führt den OAuth-2.0-Authorization-Code-Flow mit PKCE (Proof Key for Code Exchange) aus, sodass niemals ein Client Secret im Frontend-Code liegt. Sie implementieren das nicht selbst; es ist Teil der Console.

Servicekonten sind das, was Ihre Integrationen verwenden. Sie erstellen pro Integration einen Servicekonto-Client, geben ihm die minimal erforderlichen Rollen und tauschen seine client_id und sein client_secret über den Client-Credentials-Grant gegen ein Access-Token.

flowchart LR
  H["Mensch in der Console"] -->|"PKCE-Anmeldung"| IDP["KLA Identity Provider"]
  M["Backend-Dienst"] -->|"Client-Credentials"| IDP
  IDP -->|"Bearer-Token"| API["KLA Control Plane API"]

Ein Servicekonto-Token erhalten

Tauschen Sie Ihre Client-Anmeldedaten am Token-Endpunkt des Identity Providers ein. Der Realm-Pfad ist Ihr Mandant, ersetzen Sie daher <tenant> durch Ihren Mandanten-Slug.

curl -s -X POST \
  "https://auth.kla.digital/realms/<tenant>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=svc-claims-triage" \
  -d "client_secret=$KLA_CLIENT_SECRET"

Die Antwort ist ein JSON-Objekt, das das Bearer-Access-Token und seine Gültigkeitsdauer in Sekunden enthält. Das folgende Beispiel zeigt eine Antwort aus einem Dev-Realm; jede Umgebung konfiguriert ihre eigene Gültigkeitsdauer, lesen Sie daher expires_in aus jeder Antwort:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "expires_in": 1800,
  "token_type": "Bearer",
  "scope": "agents:read decisions:write"
}

Erfassen Sie das Token für die folgenden Aufrufe:

export KLA_ACCESS_TOKEN=$(curl -s -X POST \
  "https://auth.kla.digital/realms/<tenant>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=svc-claims-triage" \
  -d "client_secret=$KLA_CLIENT_SECRET" | jq -r .access_token)

Die API aufrufen

Senden Sie das Token im Authorization-Header. Der verifizierte Mandanten-Claim im Token wählt den aktuellen Mandanten aus. Der API-Host ist https://api.kla.digital. Verwenden Sie diesen Roundtrip, um zu bestätigen, dass Ihr Token funktioniert:

curl -s https://api.kla.digital/v1/tenants.current \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN"

Ein erfolgreicher Aufruf gibt den Mandanten zurück, auf den das Token beschränkt ist:

{
  "result": {
    "data": {
      "json": {
        "id": "123e4567-e89b-42d3-a456-426614174000",
        "externalId": "acme-prod",
        "name": "Acme Corp",
        "displayName": "Acme Corp",
        "branding": {
          "displayName": "Acme Corp",
          "logoUrl": null,
          "logoMarkUrl": null,
          "logoAlt": "Acme Corp",
          "accentColor": null,
          "coBranding": "kla-first"
        }
      }
    }
  }
}

Zwei optionale Header haben unterschiedliche Bedeutungen:

Ein Subjekt ohne aktive Mitgliedschaft erhält beim Versuch, einen anderen Mandanten auszuwählen, den Status 403:

curl -s https://api.kla.digital/v1/tenants.current \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-kla-tenant-external-id: another-tenant"

{ "error": "Tenant access denied" }

Die folgende Abfolge zeigt den vollständigen Pfad, den ein Maschinen-Client bei jedem Token-Zyklus durchläuft.

sequenceDiagram
  participant C as Client-Dienst
  participant IDP as KLA Identity Provider
  participant API as KLA Control Plane API
  C->>IDP: POST Token-Endpunkt mit Client-Credentials
  IDP-->>C: access_token plus expires_in
  C->>API: GET v1/tenants.current mit Bearer
  API-->>C: 200 Mandanten-Payload
  Note over C,IDP: Bei 401 abgelaufen ein frisches Token anfordern und erneut versuchen

API-Schlüssel

API-Schlüssel authentifizieren einen Maschinenaufrufer mit begrenztem Umfang in dem Mandanten, der den Schlüssel erstellt hat. Erstellen Sie einen Schlüssel über die Secrets API oder CLI und speichern Sie den zurückgegebenen Wert anschließend in Ihrem serverseitigen Secret Manager. KLA gibt den vollständigen Schlüssel nur einmal zurück.

kla api secrets createApiKey \
  --input '{"name":"approval-queue-reader","permissions":["decisions:read"]}'

Senden Sie den Schlüssel im Header x-kla-api-key. Dies ist der API-Schlüssel-Header für die Control Plane.

curl -sG "https://api.kla.digital/v1/approvals.getPending" \
  -H "x-kla-api-key: $KLA_API_KEY" \
  --data-urlencode 'input={"json":{"limit":1}}'

API-Schlüssel-Scopes werden ausschließlich über die unten dokumentierte Zuordnung erweitert. Andere gespeicherte Scope-Strings gewähren keine Berechtigungen für die Control Plane.

Der Widerruf eines API-Schlüssels ist dauerhaft. secrets.revoke akzeptiert beide Kennungen aus der Erstellungsantwort: apiKey.id oder secretId. Beide werden innerhalb des aufrufenden Tenants aufgelöst; eine unbekannte oder einem anderen Tenant zugehörige Kennung liefert NOT_FOUND. Speichern Sie apiKey.id aus der Erstellungsantwort in API_KEY_ID und widerrufen Sie den Schlüssel damit. Erstellen Sie einen Ersatzschlüssel und aktualisieren Sie die Integration, nachdem ein Schlüssel widerrufen wurde.

kla api secrets revoke --set id="$API_KEY_ID"

Token-Lebensdauer und Erneuerung

Dev-Realms stellen derzeit Access-Token mit einer Laufzeit von 30 Minuten aus (expires_in: 1800). Lesen Sie expires_in aus jeder Token-Antwort, da jede Umgebung eine andere Laufzeit konfigurieren kann. Pinnen oder cachen Sie ein Token niemals über seinen Ablauf hinaus.

• Servicekonten fordern einfach ein neues Token vom Token-Endpunkt an, wenn das aktuelle dem Ablauf nahekommt. Der Client-Credentials-Grant stellt kein Refresh-Token aus; die erneute Ausführung des Austauschs ist die Erneuerung.
• Interaktive Console-Sitzungen verwenden ein separates, langlebigeres Refresh-Token, das vom Browser verwaltet wird, um stillschweigend neue Access-Token zu erhalten.
• Ein 401 Unauthorized von der API bedeutet, dass das Token abgelaufen oder ungültig ist. Fordern Sie ein frisches Token an und versuchen Sie es einmal erneut.

Scopes und Rollen mit minimalen Rechten

Jedes Token trägt die Rollen seines Principals, und die API autorisiert jede Anfrage anhand dieser Rollen. Geben Sie einem Servicekonto nur die Rollen, die seine Aufgabe erfordert:

• Ein Agent, der Telemetrie aussendet, benötigt Schreibzugriff auf Traces, nicht die Erstellung von Richtlinien.
• Eine Genehmigungs-Automatisierung benötigt decisions:read und decisions:write, nicht die Rechte zum Deployment von Agenten.
• Ein schreibgeschützter Nachweis-Exporter benötigt Lesezugriff auf Nachweise und sonst nichts.

Erstellen Sie pro Integration ein Servicekonto, damit Sie einen einzelnen Aufrufer widerrufen oder neu zuschneiden können, ohne andere zu stören. Rollen werden im Agent Registry und in den Mandanteneinstellungen der Console verwaltet.

Servicekonto-Secrets rotieren

Ein client_secret ist eine langlebige Anmeldeinformation: Behandeln Sie es wie ein Datenbankpasswort. Rotieren Sie es nach einem festen Zeitplan und sofort bei jedem vermuteten Leck.

Speichern und rotieren Sie Servicekonto-Secrets im Secrets Vault, der Console-Oberfläche für sensible Speicherung. Erzeugen Sie dort ein neues Secret, verteilen Sie es an Ihre Integration, bestätigen Sie, dass neue Token korrekt ausgestellt werden, und nehmen Sie dann das alte Secret außer Betrieb. Der Secrets Vault unterstützt überlappende Secrets während einer Rotation, sodass Sie ohne Ausfallzeit umstellen können.

Stillgelegte API-Schlüssel

Der Widerruf eines API-Schlüssels ist dauerhaft. Für das zugehörige Secret eines widerrufenen API-Schlüssels gibt es keine Wiederherstellungs- oder Rotationsoperation. secrets.get mit includeValue: true gibt NOT_FOUND für einen widerrufenen, archivierten, abgelaufenen, fehlenden oder einem anderen Tenant zugehörigen Eintrag zurück. Autorisierte Metadatenabrufe können Lebenszyklusdaten von widerrufenen oder abgelaufenen Einträgen zurückgeben; sie geben nie den Secret-Wert zurück. Erstellen Sie einen neuen API-Schlüssel und aktualisieren Sie die Integration.