Generar token de acceso JWT
POST /api/auth/token
POST https://<api-host>/api/auth/tokenAutentíquese con el certificado de cliente X.509 + credenciales (clientId/clientSecret) y reciba un token JWT. La validez del token viene en el campo expires_in (en segundos): use ese valor para renovar el token antes de que expire, sin asumir un tiempo fijo.
Autenticación (mTLS)
Esta ruta exige mTLS: el certificado de cliente emitido por Gateways se presenta en el handshake TLS, no en un header HTTP. Use el mecanismo nativo de certificado de cliente de su biblioteca HTTP (por ejemplo, curl --cert client.crt --key client.key).
- El certificado es PEM, RSA 2048, válido por 2 años y vinculado a su cuenta.
- El mTLS se exige solo en esta ruta. Las demás rutas usan
Authorization: Bearer <token>, sin certificado.
No envíe el certificado en headers HTTP: ese modelo no se acepta. Sin el certificado en el handshake, la API responde 400 con PUB_CERT_HEADER_MISSING.
Cuerpo de la solicitud
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
clientId | string (UUID v4) | Sí | Client ID generado en el panel (https://<dashboard-host>), en Configuración → Credenciales |
clientSecret | string | Sí | Client secret generado junto con el clientId. Se muestra una única vez en el panel. No puede estar vacío |
{
"clientId": "6967c0a0-3566-48d0-8c13-717038b52279",
"clientSecret": "SU_CLIENT_SECRET"
}Ejemplo con cURL
curl -X POST https://<api-host>/api/auth/token \
--cert ./client.crt \
--key ./client.key \
-H "Content-Type: application/json" \
-d '{
"clientId": "SU_CLIENT_ID",
"clientSecret": "SU_CLIENT_SECRET"
}'Ejemplos de Código
const https = require('https');
const fs = require('fs');
const axios = require('axios');
const httpsAgent = new https.Agent({
cert: fs.readFileSync('./client.crt'),
key: fs.readFileSync('./client.key'),
});
const response = await axios.post(
'https://<api-host>/api/auth/token',
{
clientId: process.env.PIX_API_CLIENT_ID,
clientSecret: process.env.PIX_API_CLIENT_SECRET,
},
{ httpsAgent },
);
console.log('Token:', response.data.access_token);
console.log('Expira en:', response.data.expires_in, 'segundos');Gateways entrega el certificado en PEM (client.crt + client.key). Si su plataforma exige un archivo .pfx/.p12 (común en Java y en algunos entornos Windows/.NET), conviértalo localmente:
openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12La conversión se hace en su máquina; Gateways no proporciona archivos PFX.
Respuesta (201)
| Campo | Tipo | Descripción |
|---|---|---|
access_token | string | Token JWT para el header Authorization: Bearer <token> |
token_type | string | Siempre Bearer |
expires_in | number | Validez del token en segundos. Renueve antes de que expire según este valor |
scope | string | Alcance del token |
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "email profile"
}Errores
| Status | Código | Descripción |
|---|---|---|
| 400 | PUB_CERT_HEADER_MISSING | Certificado de cliente no presentado en el handshake TLS |
| 400 | PUB_CERT_MALFORMED_PEM | Certificado en formato PEM inválido |
| 400 | PUB_REQUEST_BODY_INVALID | Body inválido (ej.: clientId no es UUID v4, clientSecret vacío, campos extra). Los campos con problemas vienen en details.violations |
| 401 | PUB_INVALID_CREDENTIALS | clientId/clientSecret inválidos |
| 401 | PUB_CERT_NOT_VERIFIED | El certificado no pudo verificarse en la conexión |
| 401 | PUB_CERT_NOT_REGISTERED | Certificado no registrado |
| 401 | PUB_CERT_EXPIRED | Certificado expirado |
| 401 | PUB_CERT_NOT_YET_VALID | El certificado aún no está en su período de validez |
| 403 | PUB_CERT_NOT_AUTHORIZED_FOR_ACCOUNT | El certificado no está vinculado a la cuenta de las credenciales |
| 502 | PUB_AUTH_UPSTREAM_ERROR | Error inesperado en el servicio de autenticación |
| 503 | PUB_AUTH_UPSTREAM_UNAVAILABLE | Servicio de autenticación temporalmente no disponible. Intente nuevamente |
{
"statusCode": 401,
"timestamp": "2026-04-17T15:24:28.809Z",
"path": "/api/auth/token",
"method": "POST",
"code": "PUB_INVALID_CREDENTIALS",
"message": "Invalid credentials provided",
"userMessage": "Invalid credentials.",
"errorId": "75d7999d6d7656b737e83435ced86ec6"
}Para una guía completa de autenticación con patrones de renovación de token, vea Guía de Autenticación.