Autenticazione

Ogni chiamata all'API del KLA Control Plane viene autenticata con un bearer access token OAuth 2.0 di breve durata ed è circoscritta a un singolo tenant. Il KLA Control Plane è un livello di sicurezza, audit e governance a tempo di esecuzione, applicato in loco (govern-in-place), per gli agenti AI aziendali; la sua API è il modo in cui registri gli agenti, valuti le policy, instradi le approvazioni ed estrai le evidenze. Questa pagina spiega i due tipi di credenziali, come ottenere un token, come chiamare l'API e come mantenere le credenziali secondo il principio del privilegio minimo e con rotazione regolare.

Due tipi di credenziali

KLA emette i token tramite il proprio identity provider, un servizio OpenID Connect (OIDC). Il flusso da utilizzare dipende da chi effettua la chiamata.

L'accesso interattivo è ciò che usa la Console. Il browser esegue il flusso OAuth 2.0 Authorization Code con PKCE (Proof Key for Code Exchange), così nessun client secret risiede mai nel codice del front-end. Non devi implementarlo tu: è già incluso nella Console.

Gli account di servizio sono ciò che usano le tue integrazioni. KLA crea su richiesta un client di tipo account di servizio per il tuo tenant; gli assegni i ruoli minimi necessari e scambi il suo client_id e client_secret con un access token tramite il grant client credentials. Un agente che richiede decisioni o propone azioni non ha bisogno di un account di servizio: un amministratore del tenant crea per lui una chiave API con ambiti definiti (vedi Chiavi API più sotto) e gli SDK di governance accettano quella chiave.

flowchart LR
  H["Persona nella Console"] -->|"accesso PKCE"| IDP["KLA identity provider"]
  M["Servizio di backend"] -->|"client credentials"| IDP
  IDP -->|"bearer token"| API["KLA Control Plane API"]

Ottenere un token per un account di servizio

Scambia le tue client credentials presso l'endpoint dei token dell'identity provider. Il percorso del realm corrisponde al tuo tenant, quindi sostituisci <tenant> con lo slug del tuo 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 risposta è un oggetto JSON che contiene il bearer access token e la sua durata in secondi. L'esempio seguente mostra una risposta di un realm di dev; ogni ambiente configura la propria durata, quindi leggi expires_in da ogni risposta:

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

Cattura il token per le chiamate che seguono:

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)

Chiamare l'API

Invia il token nell'header Authorization. Il claim del tenant verificato nel token seleziona il tenant corrente. L'host dell'API è https://api.kla.digital. Usa questa chiamata di andata e ritorno per verificare che il tuo token funzioni:

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

Una chiamata riuscita restituisce il tenant a cui il token è circoscritto:

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

Due header facoltativi hanno significati diversi:

Un soggetto senza un'appartenenza attiva riceve 403 quando tenta di selezionare un altro 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 sequenza seguente mostra l'intero percorso che un client macchina segue a ogni ciclo del token.

sequenceDiagram
  participant C as Servizio client
  participant IDP as KLA identity provider
  participant API as KLA Control Plane API
  C->>IDP: POST all'endpoint dei token con le client credentials
  IDP-->>C: access_token e expires_in
  C->>API: GET v1/tenants.current con bearer
  API-->>C: 200 payload del tenant
  Note over C,IDP: In caso di 401 scaduto, richiedi un nuovo token e riprova

Chiavi API

Le chiavi API autenticano un chiamante macchina con scope limitato nel tenant che ha creato la chiave. Crea una chiave con l'API Secrets o la CLI, quindi archivia il valore restituito nel tuo gestore di segreti lato server. KLA restituisce la chiave completa una sola volta.

kla api secrets createApiKey \
  --input '{"name":"kyc-onboarding-agent","permissions":["actions:propose","policy:evaluate"],"expiresAt":"2027-01-07"}'

Invia la chiave nell'header x-kla-api-key. Questo è l'header della chiave API per il 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}}'

Un agente con actions:propose invia lo stesso corpo di proposta inviato dagli SDK di governance. Gli SDK di governance inviano la stessa intestazione quando passi la chiave come apiKey (Node.js) o api_key (Python). Accettano anche un token bearer client-credentials come credential; un client usa uno dei due.

curl -s -X POST "https://api.kla.digital/v1/agent-actions" \
  -H "x-kla-api-key: $KLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @proposal.json

Un agente con policy:evaluate che esegue i propri strumenti chiede una decisione prima di ogni chiamata a uno strumento. KLA registra la decisione e non esegue nulla; l’agente agisce in base al risultato. Lo strumento deve essere una voce attiva del Tool Catalog del tenant:

curl -s -X POST "https://api.kla.digital/v1/policy/evaluate" \
  -H "x-kla-api-key: $KLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "occurredAt": "2026-10-10T09:00:00Z",
      "identifiers": {
        "workspaceId": "<tenant external ID>",
        "runId": "onboarding-case-1042",
        "gateId": "open-account-1",
        "agentId": "<agent ID>",
        "environment": "production"
      },
      "action": {
        "actionType": "tool_call",
        "toolName": "open_customer_account",
        "toolArgs": { "risk_score": 15, "pep_match": false, "sanctions_hit": false }
      }
    },
    "policyReference": { "policyId": "kyc-onboarding-gate" }
  }'

KLA ricava l’identità del chiamante e i permessi sullo strumento dalla chiave e dal Tool Catalog, quindi il corpo non contiene alcun oggetto entitlements. La risposta decision.decision è allow, warn, require_approval o block. Una decisione require_approval apre una Decision Request nel Decision Desk. Una risposta 400 elenca ogni campo non valido con il suo percorso completo in issues.paths.

Gli scope delle chiavi API si espandono solo tramite la mappatura documentata qui sotto. Altre stringhe di scope memorizzate non concedono autorizzazioni al Control Plane.

Qualsiasi altro valore di ambito viene rifiutato alla creazione con 400 BAD_REQUEST. Una chiave raggiunge solo le operazioni dei propri ambiti; ogni altra richiesta restituisce 403 (api_key_scope_denied).

La revoca di una chiave API è permanente. secrets.revoke accetta entrambi gli identificatori restituiti dalla risposta di creazione: apiKey.id o secretId. Entrambi vengono risolti all'interno del tenant chiamante; un identificatore sconosciuto o appartenente a un altro tenant restituisce NOT_FOUND. Salva apiKey.id dalla risposta di creazione in API_KEY_ID, poi revoca la chiave con quel valore. Crea una chiave sostitutiva e aggiorna l'integrazione dopo la revoca di una chiave.

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

Durata e rinnovo del token

I realm di dev emettono attualmente access token con una durata di 30 minuti (expires_in: 1800). Leggi expires_in in ogni risposta del token, poiché ogni ambiente può configurare una durata diversa. Non fissare né memorizzare mai un token nella cache oltre la scadenza.

• Gli account di servizio richiedono semplicemente un nuovo token all'endpoint dei token quando quello corrente si avvicina alla scadenza. Il grant client credentials non rilascia un refresh token; il rinnovo consiste nel rieseguire lo scambio.
• Le sessioni interattive della Console utilizzano un refresh token separato e a durata più lunga, gestito dal browser per ottenere silenziosamente nuovi access token.
• Un 401 Unauthorized da parte dell'API significa che il token è scaduto o non valido. Richiedi un nuovo token e riprova una volta.

Scope e ruoli a privilegio minimo

Ogni token porta con sé i ruoli del proprio principal e l'API autorizza ogni richiesta in base ad essi. Concedi a un account di servizio solo i ruoli richiesti dal suo compito:

• Un agente che emette telemetria necessita dell'accesso in scrittura alle tracce, non della creazione di policy.
• Un runtime dell'agente necessita di actions:propose, e di policy:evaluate se richiede decisioni prima di agire. Non necessita di diritti di deployment degli agenti.
• Un monitor della coda necessita di decisions:read e di nient'altro.
• Un esportatore di evidenze in sola lettura necessita dell'accesso in lettura alle evidenze e nient'altro.

Crea un account di servizio per ogni integrazione, così da poter revocare o ridefinire gli scope di un singolo chiamante senza interrompere gli altri. I ruoli si gestiscono nell'Agent Registry e nelle impostazioni del tenant della Console.

Rotazione dei segreti degli account di servizio

Un client_secret è una credenziale a lunga durata: trattalo come la password di un database. Ruotalo a cadenza regolare e immediatamente in caso di sospetta esposizione.

Memorizza e ruota i segreti degli account di servizio nel Secrets Vault, la superficie della Console dedicata all'archiviazione di dati sensibili. Genera lì un nuovo segreto, distribuiscilo alla tua integrazione, verifica che i nuovi token vengano emessi correttamente e quindi ritira il vecchio segreto. Il Secrets Vault supporta segreti sovrapposti durante una rotazione, così da poter procedere con zero tempi di inattività.

Record di chiavi API ritirate

La revoca di una chiave API è permanente. Il segreto di supporto di una chiave API revocata non dispone di un'operazione di ripristino o rotazione. secrets.get con includeValue: true restituisce NOT_FOUND per un record revocato, archiviato, scaduto, assente o appartenente a un altro tenant. Le letture autorizzate dei metadati possono restituire dati del ciclo di vita di record revocati o scaduti; non restituiscono mai il valore del segreto. Crea una nuova chiave API e aggiorna l'integrazione.