Saltar al contenido principal

OAuth2 (client credentials)

Las integraciones entre servidores pueden usar el flujo estándar client credentials (RFC 6749 §4.4): un cliente OAuth ligado a una de tus claves API cambia su client_id y su client_secret por un token de acceso que se envía como Bearer. Así la clave API no viaja en cada petición y puedes rotar el secreto sin tocar la clave.

Cuándo usarlo

Es una alternativa a la clave API, no un permiso adicional: el token actúa como su clave (misma cuenta, ámbitos, límites, cuota mensual, listas de IP y orígenes permitidos, y modo pruebas). No hay refresh tokens: pide uno nuevo al caducar.

En los ejemplos, $BASE es la dirección de tu plataforma.

Crear un cliente OAuth​

Hoy no hay pantalla para esto: se gestiona con la API de administración, con una sesión de administrador que tenga el permiso Gestionar clientes OAuth2 (Pages.Administration.ApiKeys.OAuthClients) y una clave API existente de tu cuenta.

LlamadaQué hace
POST /api/services/app/ApiOAuthClient/CreateCrea el cliente. Cuerpo: apiKeyId, name (hasta 256), description (opcional)
GET /api/services/app/ApiOAuthClient/GetAllLista los clientes (sin secretos)
POST /api/services/app/ApiOAuthClient/RotateSecretCuerpo: id, revokeIssuedTokens. Devuelve un secreto nuevo
POST /api/services/app/ApiOAuthClient/RevokeCuerpo: id. Anula el cliente

Create devuelve clientId (empieza por oc_), clientSecret (empieza por ocs_) y tokenEndpoint.

Copia el secreto ahora

El client_secret solo se muestra una vez, al crear el cliente o al rotarlo. Guárdalo en un gestor de secretos, nunca en el código.

Si la clave tiene ámbitos de administración (Ámbitos de administración), crear o rotar su cliente exige además el permiso Pages.Administration.ApiKeys.AdminScopes.

Pedir un token​

curl -s -X POST "$BASE/connect/token" \
  -d grant_type=client_credentials \
  -d client_id=oc_xxxxxxxx \
  -d client_secret=ocs_xxxxxxxx \
  -d "scope=read programs:read"
# {"access_token":"eyJ...","token_type":"Bearer","expires_in":3599,"scope":"read programs:read"}
  • Formato application/x-www-form-urlencoded. En lugar de client_id y client_secret en el cuerpo puedes usar HTTP Basic (Authorization: Basic base64(client_id:client_secret)).
  • scope es opcional y va separado por espacios. Sin él, el token lleva todos los ámbitos de la clave; con él, solo los que pidas, que deben ser un subconjunto de los de la clave.
  • El token dura 60 minutos por defecto (expires_in indica los segundos restantes). Reutilízalo hasta que caduque.

Úsalo igual que una clave:

curl -s "$BASE/api/v1/programs" -H "Authorization: Bearer eyJ..."

Errores​

Los del endpoint de token siguen el RFC 6749 §5.2:

CódigoerrorCuándo
401invalid_clientclient_id o client_secret incorrectos, o cliente revocado
400invalid_scopePides un ámbito que la clave no tiene
400unauthorized_clientLa clave está inactiva o caducada, la IP o el origen no están permitidos, la cuenta está inactiva o su plan no incluye acceso por API

Un token caducado, alterado o de un cliente revocado o rotado recibe 401 con la cabecera WWW-Authenticate: Bearer error="invalid_token": pide uno nuevo.

Rotar y revocar​

  • Rotar (RotateSecret): el secreto anterior deja de funcionar al instante. Los tokens ya emitidos siguen valiendo hasta que caducan, lo que permite cambiar de secreto sin cortes. Si el secreto se ha filtrado, envía revokeIssuedTokens: true y se rechazan también esos tokens.
  • Revocar (Revoke): el cliente, su secreto y todos sus tokens dejan de funcionar. Revocar o borrar la clave API tiene el mismo efecto; regenerarla mantiene sus clientes OAuth.
  • Quitar un ámbito a la clave lo quita también de los tokens ya emitidos.

Siguientes pasos​