Authentification

Chaque appel à l'API KLA Control Plane est authentifié par un jeton d'accès porteur OAuth 2.0 de courte durée et restreint à un seul tenant. Le KLA Control Plane est une couche de sécurité à l'exécution, d'audit et de gouvernance en place pour les agents IA d'entreprise ; son API permet d'enregistrer des agents, d'évaluer des politiques, d'acheminer des approbations et d'extraire des preuves. Cette page présente les deux types d'identifiants, la manière d'obtenir un jeton, la façon d'appeler l'API et les bonnes pratiques pour garder des identifiants au moindre privilège et régulièrement renouvelés.

Deux types d'identifiants

KLA émet des jetons par l'intermédiaire de son fournisseur d'identité, un service OpenID Connect (OIDC). Le flux à utiliser dépend de l'appelant.

La connexion interactive est celle qu'utilise la Console. Le navigateur exécute le flux OAuth 2.0 Authorization Code avec PKCE (Proof Key for Code Exchange), de sorte qu'aucun secret client ne se trouve jamais dans le code front-end. Vous n'avez pas à l'implémenter vous-même : elle est fournie avec la Console.

Les comptes de service sont ce qu'utilisent vos intégrations. Vous créez un client de compte de service par intégration, vous lui accordez les rôles minimaux dont il a besoin, puis vous échangez son client_id et son client_secret contre un jeton d'accès via le grant client credentials.

flowchart LR
  H["Humain dans la Console"] -->|"Connexion PKCE"| IDP["Fournisseur d'identité KLA"]
  M["Service backend"] -->|"client credentials"| IDP
  IDP -->|"jeton porteur"| API["API KLA Control Plane"]

Obtenir un jeton de compte de service

Échangez vos identifiants client auprès du point de terminaison de jeton du fournisseur d'identité. Le chemin du realm correspond à votre tenant : remplacez donc <tenant> par le slug de votre tenant.

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"

La réponse est un objet JSON contenant le jeton d'accès porteur et sa durée de vie en secondes. L'exemple ci-dessous montre une réponse d'un realm de dev ; chaque environnement configure sa propre durée de vie, lisez donc expires_in dans chaque réponse :

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

Conservez le jeton pour les appels qui suivent :

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)

Appeler l'API

Envoyez le jeton dans l'en-tête Authorization. Le claim de tenant vérifié du jeton sélectionne le tenant actuel. L'hôte de l'API est https://api.kla.digital. Utilisez cet aller-retour pour vérifier que votre jeton fonctionne :

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

Un appel réussi renvoie le tenant auquel le jeton est restreint :

{
  "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"
        }
      }
    }
  }
}

Deux en-têtes facultatifs ont des significations différentes :

Un sujet sans adhésion active reçoit 403 lorsqu'il tente de sélectionner un autre tenant :

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" }

La séquence ci-dessous illustre le chemin complet qu'un client machine suit à chaque cycle de jeton.

sequenceDiagram
  participant C as Service client
  participant IDP as Fournisseur d'identité KLA
  participant API as API KLA Control Plane
  C->>IDP: POST point de terminaison de jeton avec client credentials
  IDP-->>C: access_token et expires_in
  C->>API: GET v1/tenants.current avec porteur
  API-->>C: 200 charge utile du tenant
  Note over C,IDP: En cas de 401 expiré, demander un nouveau jeton et réessayer

Clés API

Les clés API authentifient un appelant machine à portée limitée dans le tenant qui a créé la clé. Créez une clé avec l'API Secrets ou la CLI, puis stockez la valeur renvoyée dans votre gestionnaire de secrets côté serveur. KLA renvoie la clé complète une seule fois.

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

Envoyez la clé dans l'en-tête x-kla-api-key. Il s'agit de l'en-tête de clé API pour le 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}}'

Les portées des clés API ne s'étendent que selon le mappage documenté ci-dessous. Aucune autre chaîne de portée stockée n'accorde de permission au Control Plane.

La révocation d'une clé API est définitive. secrets.revoke accepte l'un ou l'autre des identifiants renvoyés par la réponse de création : apiKey.id ou secretId. Les deux sont résolus dans le tenant appelant ; un identifiant inconnu ou appartenant à un autre tenant renvoie NOT_FOUND. Stockez apiKey.id de la réponse de création dans API_KEY_ID, puis révoquez la clé avec cette valeur. Créez une clé de remplacement et mettez à jour l'intégration après la révocation d'une clé.

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

Durée de vie et renouvellement des jetons

Les realms de dev émettent actuellement des jetons d'accès d'une durée de 30 minutes (expires_in: 1800). Lisez expires_in dans chaque réponse de jeton, car chaque environnement peut configurer une durée différente. Ne figez jamais et ne mettez jamais en cache un jeton au-delà de son expiration.

• Les comptes de service demandent simplement un nouveau jeton au point de terminaison de jeton lorsque le jeton courant approche de son expiration. Le grant client credentials n'émet pas de jeton de rafraîchissement : c'est la réexécution de l'échange qui fait office de rafraîchissement.
• Les sessions interactives de la Console utilisent un jeton de rafraîchissement distinct et à durée de vie plus longue, géré par le navigateur, pour obtenir silencieusement de nouveaux jetons d'accès.
• Un 401 Unauthorized renvoyé par l'API signifie que le jeton est expiré ou invalide. Demandez un nouveau jeton et réessayez une fois.

Portées et rôles au moindre privilège

Chaque jeton porte les rôles de son principal, et l'API autorise chaque requête en fonction de ceux-ci. N'accordez à un compte de service que les rôles requis par sa mission :

• Un agent qui émet de la télémétrie a besoin d'un accès en écriture aux traces, pas de l'écriture de politiques.
• Une automatisation d'approbations a besoin de decisions:read et decisions:write, pas de droits de déploiement d'agents.
• Un exporteur de preuves en lecture seule a besoin d'un accès en lecture aux preuves et de rien d'autre.

Créez un compte de service par intégration, afin de pouvoir révoquer ou redéfinir la portée d'un seul appelant sans perturber les autres. Les rôles se gèrent dans l'Agent Registry et dans les paramètres du tenant de la Console.

Renouveler les secrets de compte de service

Un client_secret est un identifiant à longue durée de vie : traitez-le comme un mot de passe de base de données. Renouvelez-le selon un calendrier régulier et immédiatement en cas de suspicion d'exposition.

Stockez et renouvelez les secrets de compte de service dans le Secrets Vault, la surface de la Console dédiée au stockage sensible. Générez-y un nouveau secret, déployez-le sur votre intégration, vérifiez que les nouveaux jetons sont bien émis, puis retirez l'ancien secret. Le Secrets Vault prend en charge le chevauchement de secrets pendant une rotation, ce qui vous permet de passer à la nouvelle version sans aucune interruption de service.

Enregistrements de clés API retirées

La révocation d'une clé API est définitive. Le secret associé à une clé API révoquée ne dispose d'aucune opération de restauration ou de rotation. secrets.get avec includeValue: true renvoie NOT_FOUND pour un enregistrement révoqué, archivé, expiré, absent ou appartenant à un autre tenant. Les lectures de métadonnées autorisées peuvent renvoyer les données de cycle de vie des enregistrements révoqués ou expirés ; elles ne renvoient jamais la valeur du secret. Créez une nouvelle clé API et mettez à jour l'intégration.