Documentación
Autenticación
OAuth2 Client Credentials: cómo se obtiene un token, cuánto dura y cuándo deja de valer.
La API usa OAuth2 Client Credentials (RFC 6749 §4.4), el flujo pensado para que un programa hable con otro sin que haya una persona delante. No hay pantalla de consentimiento ni redirecciones: se intercambian dos secretos por un token de vida corta.
client_id + client_secret
│
▼
POST https://api.niucore.com/api/oauth/token
│
▼
access_token (JWT, ~1 h)
│
▼
Authorization: Bearer … → https://api.niucore.com/api/v1/…Las credenciales
Una credencial son dos valores. El client_id (nc_…) es público e identifica la integración; el client_secret (ncs_…) es privado y se muestra una sola vez, al crearla o al rotarla.
Del secreto solo se guarda su HMAC-SHA256 con un *pepper* que vive fuera de la base. Ni siquiera un volcado completo de la base alcanza para autenticarse — y por eso no existe forma de recuperarlo: si se pierde, se rota.
Un secreto de máquina
El client_secret va en un gestor de secretos o en una variable de entorno del servidor. Nunca en un frontend, una app móvil, un repositorio o una URL: quien lo tenga puede actuar como el usuario titular con todo el alcance de la credencial.
Pedir un token
Se admiten los dos métodos estándar de autenticación de cliente, pero no los dos a la vez: mandar las credenciales por Authorization: Basic y en el cuerpo al mismo tiempo devuelve invalid_request, porque deja ambiguo cuál gana.
| Método | Cómo |
|---|---|
client_secret_basic | Authorization: Basic base64(client_id:client_secret). Es el recomendado: el secreto no aparece en el cuerpo. |
client_secret_post | client_id y client_secret como campos del formulario. |
curl -sS -X POST 'https://api.niucore.com/api/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-u "$NIUCORE_CLIENT_ID:$NIUCORE_CLIENT_SECRET" \
-d 'grant_type=client_credentials' \
-d 'scope=chat:read chat:write'Sugerencia
Cacheá el token y renovalo un poco antes de expires_in. Pedir uno nuevo en cada request funciona, pero gasta la cubeta del client_id (60 pedidos por minuto) sin necesidad.
El parámetro scope
scope es opcional y solo sirve para recortar. Sin él, el token sale con todos los scopes vigentes de la credencial; con él, solo con los que pidas. Pedir un scope que la credencial no tiene devuelve invalid_scope y nombra cuáles fallaron.
Pedir el mínimo necesario es una buena práctica: si el token se filtra, el daño queda acotado a lo que ese proceso realmente hacía.
Usar el token
GET https://api.niucore.com/api/v1/chats HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept-Language: esEl token es un JWT firmado, pero tratalo como opaco: sus claims son un detalle interno y pueden cambiar. Si necesitás saber si sigue vigente, usá `POST /api/oauth/introspect`.
Cuándo deja de valer
Un token vale hasta que pasa cualquiera de estas cosas. Todas producen 401 con WWW-Authenticate: Bearer error="invalid_token", y todas se resuelven pidiendo un token nuevo — salvo las dos últimas, que necesitan intervención humana.
| Causa | Qué hacer |
|---|---|
Venció (expires_in). | Pedir otro. |
| Se rotó el secreto de la credencial. | Actualizar el client_secret y pedir otro. Los tokens viejos mueren en el request siguiente, sin esperar a que venzan. |
| Se revocó el token (RFC 7009). | Pedir otro. |
| Se revocó o venció la credencial. | Crear una nueva desde la aplicación. Pedir un token devuelve invalid_client. |
| El usuario titular se desactivó, cambió de empresa o perdió el rol. | La credencial queda sin fundamento. Hay que crear otra con un titular vigente. |
Anti-enumeración
Un client_id inexistente, un secreto incorrecto y una credencial revocada devuelven el mismo invalid_client, y el servidor hace el mismo trabajo criptográfico en los tres casos. No se puede distinguir uno de otro ni por la respuesta ni por el tiempo.
Descubrimiento
Si tu cliente OAuth sabe leer metadata RFC 8414, apuntalo a https://api.niucore.com/.well-known/oauth-authorization-server y se configura solo: endpoints, grants, métodos de autenticación y catálogo de scopes.