---
title: Autenticación
description: Flujo OAuth2 JWT Bearer utilizado por todos los contratos de IDCloud. Aprenda cómo obtener credenciales, construir la aserción JWT e intercambiarla por un token de acceso.
canonical: https://developer.unico.io/es/dual-api/developers/api-reference/authentication
locale: es
generated_by: markdown-export
---

- [/es/](/es/)
- [Referencia de API](/es/dual-api/developers/api-reference/)
- Autenticación

**En esta página# Autenticación

Todas las APIs de IDCloud (contratos Web & SDK y API) usan **OAuth2 con JWT Bearer Grant Type** ([RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)). Usted genera una aserción JWT de corta duración en su back-end, la intercambia por un token Bearer y usa ese token en cada llamada posterior.
Nunca haga esto del lado del clienteLa aserción JWT debe generarse únicamente en su **back-end**. Nunca exponga su clave privada en código front-end, aplicaciones móviles, repositorios ni logs.
### Obtención de credenciales​

Antes de poder generar tokens, necesita una **cuenta de servicio** aprovisionada por Unico. Contacte al soporte de Unico y proporcione:

Nombre de la cuenta de servicio (máximo 12 caracteres)
Nombre, correo electrónico y teléfono del responsable (solo números de Brasil, EE. UU. o México)

Recibirá:

Nombre único de cuenta
Tenant ID
Payload JWT base
Archivo de clave privada (formato `.pem`)

Una cuenta por entornoMantenga cuentas de servicio separadas para **UAT** y **Producción**.
### Construcción de la aserción JWT​

La aserción es un JWT en formato JWS compacto: `{Base64url(Header)}.{Base64url(Payload)}.{Base64url(Signature)}`.
Header
```
{  "alg": "RS256",  "typ": "JWT"}
```

Payload
ClaimValorNotas`iss``<account_name>@<tenant_id>.iam.acesso.io`Proporcionado con sus credenciales`aud``https://identityhomolog.acesso.io` (UAT) o `https://identity.acesso.io` (Producción)Debe coincidir con el host del endpoint de token`scope``*`Otorga todos los permisos`iat`Marca de tiempo Unix (segundos)Hora en que se emitió el JWT`exp``iat` + máximo 3600No puede superar 1 hora desde `iat`
```
{  "iss": "my-account@abc123.iam.acesso.io",  "aud": "https://identity.acesso.io",  "scope": "*",  "iat": 1738086000,  "exp": 1738089600}
```

Signature
Firme el header + payload usando **RS256** (RSA + SHA-256) con la clave privada `.pem` proporcionada por Unico.
No agregue claims adicionalesCualquier campo no listado anteriormente (p. ej. `sub`, `jti`, `nbf`) causará un error `1.2.22`. Use solo los claims mostrados.
### Solicitud del token​

El endpoint de token es el mismo para ambos contratos:
EntornoEndpoint**Producción**`POST https://identity.acesso.io/oauth2/token`**UAT**`POST https://identityhomolog.acesso.io/oauth2/token`
Request
ParámetroValor`Content-Type``application/x-www-form-urlencoded``grant_type``urn:ietf:params:oauth:grant-type:jwt-bearer``assertion`Su JWT firmado
cURLNode.jsPython```
curl -X POST https://identity.acesso.io/oauth2/token \  -H "Content-Type: application/x-www-form-urlencoded" \  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \  -d "assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

```
import jwt from 'jsonwebtoken';import fs from 'fs';import qs from 'querystring';const privateKey = fs.readFileSync('./private-key.pem');const now = Math.floor(Date.now() / 1000);const assertion = jwt.sign(  {    iss: 'my-account@abc123.iam.acesso.io',    aud: 'https://identity.acesso.io',    scope: '*',    iat: now,    exp: now + 3600,  },  privateKey,  { algorithm: 'RS256' });const res = await fetch('https://identity.acesso.io/oauth2/token', {  method: 'POST',  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },  body: qs.stringify({    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',    assertion,  }),});const { access_token, expires_in } = await res.json();
```

```
import timeimport jwt  # PyJWTimport requestswith open("private-key.pem", "rb") as f:    private_key = f.read()now = int(time.time())assertion = jwt.encode(    {        "iss": "my-account@abc123.iam.acesso.io",        "aud": "https://identity.acesso.io",        "scope": "*",        "iat": now,        "exp": now + 3600,    },    private_key,    algorithm="RS256",)response = requests.post(    "https://identity.acesso.io/oauth2/token",    data={        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",        "assertion": assertion,    },)token_data = response.json()access_token = token_data["access_token"]
```

Response
```
{  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",  "token_type": "Bearer",  "expires_in": 3600}
```

CampoTipoDescripción`access_token`stringToken de acceso JWT. Úselo en `Authorization: Bearer <token>` en todas las llamadas a la API.`expires_in`integerTiempo de expiración en segundos. Ejemplo: `3600`.`token_type`stringSiempre `Bearer`.
### Uso del token​

Agregue el token al encabezado `Authorization` de cada solicitud a la API. El encabezado es idéntico para ambos contratos — lo que difiere es el **host y el path** de la API que está llamando:
ContratoHost de producciónHost de UAT**Web & SDK**`https://api.idcloud.unico.app``https://api.idcloud.uat.unico.app`**API**`https://api.id.unico.app``https://api.id.uat.unico.app`
**Web & SDK** — `Authorization` es el único encabezado de autenticación requerido:
```
curl -X POST https://api.idcloud.unico.app/client/v1/process \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{ ... }'
```

**API** — `Authorization` se usa junto con el encabezado `APIKEY`:
```
curl -X POST https://api.id.unico.app/processes/v1 \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H "APIKEY: $API_KEY" \  -H "Content-Type: application/json" \  -d '{ ... }'
```

### Renovación del token​

Los tokens expiran después de 3600 segundos. Implemente la renovación proactiva en su back-end:

Registre `expires_in` de la respuesta del token y almacene la marca de tiempo de expiración.
Solicite un nuevo token **cuando queden 10 minutos o menos** antes de la expiración.
Nunca espere un `401` en producción para activar la renovación.

### Referencia de API​

La especificación OpenAPI completa para el endpoint de token está disponible en [`authentication.yaml`](/es/assets/files/authentication-1d221f9a7230435e9c390ba98dac7321.yaml).
MétodoPathDescripción`POST``/oauth2/token`Intercambia una aserción JWT firmada por un token de acceso Bearer
### Códigos de error​

CódigoDescripciónAcción`1.0.1`El ID proporcionado en la formación de `iss` es incorrectoVerifique que el campo `iss` coincida con el tenant ID proporcionado al generar la clave privada`1.0.14`La aplicación no está activaConsulte con el gestor del proyecto si la aplicación utilizada está activa`1.1.1`El parámetro `scope` no fue proporcionadoAgregue `"scope": "*"` a su payload JWT`1.2.4`Aserción JWT inválidaLa aserción JWT ya no es válida. Dos causas: (a) el tiempo actual supera `exp` (JWT verdaderamente expirado — genere una nueva aserción para cada solicitud de token); o (b) `exp` supera `iat + 3600` (vida útil demasiado larga — limite `exp` a `iat + 3600`).`1.2.5`La validación del JWT fallóEl JWT no puede ser validado. Verifique los parámetros y asegúrese de que fue firmado con RS256 y la clave privada correcta`1.2.6`La clave privada ya no es válidaLa clave privada usada para firmar el JWT ya no es aceptable. Solicite nuevas credenciales para la cuenta`1.2.7`El JWT ya fue utilizadoEl JWT ya no es aceptable porque ya fue utilizado. Genere una nueva aserción para cada solicitud de token`1.2.11`La cuenta no está activaLa cuenta utilizada no está activa`1.2.14`La cuenta carece de los permisos necesariosLa cuenta utilizada no tiene los permisos necesarios`1.2.18`Cuenta temporalmente bloqueadaLa cuenta ha sido temporalmente bloqueada por exceder el número de intentos de autenticación inválidos`1.2.19`Suplantación de usuario no autorizadaEl JWT contiene un claim `sub` que apunta a una cuenta no autorizada para suplantación. Elimine el claim `sub` del payload.`1.2.20`Error al decodificar el JWTNo se pudo decodificar el JWT. Verifique el formato del token y que haya sido firmado con RS256.`1.2.21`Clave privada incorrecta / Autenticación fallidaLa firma del JWT no pudo verificarse con ninguna clave conocida para esta cuenta. Compruebe que está usando la clave privada `.pem` correcta para esta cuenta de servicio y entorno.`1.2.22`Campos no permitidos en el payloadEl JWT contiene campos de payload adicionales que no están permitidos. Elimine cualquier claim no listado en esta guía (p. ej. `sub`, `jti`, `nbf`). Nota: si incluyó un claim `sub` y recibió `1.2.19`, ese error tiene precedencia.`1.3.1`Restricción de acceso por IPSu IP no está en la lista de permitidos para esta cuenta`1.3.2`Restricción de acceso por horarioLa solicitud está fuera de la ventana de tiempo permitida para esta cuenta
### Próximos pasos​

[Entornos](/es/dual-api/developers/api-reference/environments) — hosts de sandbox vs producción
[Web & SDK — Crear proceso](/es/dual-api/developers/api-reference/web-sdk/post-process) — primera llamada tras la autenticación
[API — Crear proceso](/es/dual-api/developers/api-reference/api/post-processes) — primera llamada tras la autenticación
[SSO / SAML](/es/dual-api/developers/api-reference/sso-saml) — autentique a sus usuarios en los portales de productos de Unico con su propio proveedor de identidad, en lugar del flujo servidor a servidor anterior
Última actualización el 8 oct 2026**