Autenticación

Cada llamada a la API de KLA Control Plane se autentica con un token de acceso bearer OAuth 2.0 de corta duración y queda acotada a un único tenant. El KLA Control Plane es una capa de seguridad, auditoría y gobernanza en tiempo de ejecución que gobierna en el lugar (govern-in-place) para agentes de IA empresariales; su API es la forma en que registras agentes, evalúas políticas, enrutas aprobaciones y extraes evidencias. Esta página explica los dos tipos de credenciales, cómo obtener un token, cómo llamar a la API y cómo mantener las credenciales con el mínimo privilegio y debidamente rotadas.

Dos tipos de credenciales

KLA emite tokens a través de su proveedor de identidad, un servicio OpenID Connect (OIDC). El flujo que uses depende de quién realiza la llamada.

El inicio de sesión interactivo es lo que usa la Console. El navegador ejecuta el flujo OAuth 2.0 de Authorization Code con PKCE (Proof Key for Code Exchange), de modo que ningún client secret reside jamás en el código del front-end. No tienes que implementarlo tú mismo; viene incluido con la Console.

Las cuentas de servicio son las que usan tus integraciones. Creas un cliente de cuenta de servicio por integración, le concedes los roles mínimos que necesita e intercambias su client_id y client_secret por un token de acceso usando el grant de client-credentials.

flowchart LR
  H["Persona en la Console"] -->|"Inicio de sesión PKCE"| IDP["Proveedor de identidad de KLA"]
  M["Servicio de backend"] -->|"client credentials"| IDP
  IDP -->|"token bearer"| API["API de KLA Control Plane"]

Obtener un token de cuenta de servicio

Intercambia tus credenciales de cliente en el endpoint de token del proveedor de identidad. La ruta del realm es tu tenant, así que sustituye <tenant> por el slug de tu 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 respuesta es un objeto JSON que contiene el token de acceso bearer y su tiempo de vida en segundos:

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

Captura el token para las llamadas que siguen:

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)

Llamar a la API

Envía el token en el encabezado Authorization e indica tu tenant en el encabezado x-tenant-id. El host de la API es https://api.kla.digital. Usa esta comprobación de ida y vuelta para confirmar que tu token funciona:

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

Una llamada exitosa devuelve el tenant al que está acotado el token:

{
  "tenant": { "id": "acme", "name": "Acme Corp", "region": "eu" }
}

La secuencia siguiente muestra el recorrido completo que sigue un cliente de máquina en cada ciclo de token.

sequenceDiagram
  participant C as Servicio cliente
  participant IDP as Proveedor de identidad de KLA
  participant API as API de KLA Control Plane
  C->>IDP: POST al endpoint de token con client credentials
  IDP-->>C: access_token más expires_in
  C->>API: GET v1/tenants.current con bearer más x-tenant-id
  API-->>C: 200 payload del tenant
  Note over C,IDP: En 401 expirado, solicita un token nuevo y reintenta

Tiempo de vida y renovación del token

Los tokens de acceso son de corta duración, normalmente cinco minutos (expires_in: 300). Esto limita el radio de impacto de un token filtrado. No fijes ni almacenes en caché un token más allá de su expiración.

• Las cuentas de servicio simplemente solicitan un nuevo token al endpoint de token cuando el actual se acerca a su expiración. El grant de client-credentials no emite un refresh token; volver a ejecutar el intercambio es la renovación.
• Las sesiones interactivas de la Console usan un refresh token independiente y de mayor duración, gestionado por el navegador, para obtener nuevos tokens de acceso de forma silenciosa.
• Un 401 Unauthorized de la API significa que el token está expirado o no es válido. Solicita un token nuevo y reintenta una vez.

Scopes y roles de mínimo privilegio

Cada token lleva consigo los roles de su principal, y la API autoriza cada solicitud frente a ellos. Concede a una cuenta de servicio solo los roles que requiere su tarea:

• Un agente que emite telemetría necesita acceso de escritura a las trazas, no a la autoría de políticas.
• Una automatización de aprobaciones necesita decisions:read y decisions:write, no derechos de despliegue de agentes.
• Un exportador de evidencias de solo lectura necesita acceso de lectura a las evidencias y nada más.

Crea una cuenta de servicio por integración para poder revocar o reajustar el scope de un único llamante sin afectar a los demás. Los roles se gestionan en el Agent Registry y en la configuración del tenant de la Console.

Rotar los secretos de las cuentas de servicio

Un client_secret es una credencial de larga duración: trátala como la contraseña de una base de datos. Rótala según un calendario e inmediatamente ante cualquier sospecha de exposición.

Almacena y rota los secretos de las cuentas de servicio en el Secrets Vault, la superficie de la Console para el almacenamiento sensible. Genera allí un nuevo secreto, despliégalo en tu integración, confirma que los nuevos tokens se generan correctamente y, a continuación, retira el secreto antiguo. El Secrets Vault admite secretos solapados durante una rotación, de modo que puedas avanzar sin tiempo de inactividad.