Gerar token de acesso JWT
POST /api/auth/token
POST https://<api-host>/api/auth/tokenAutentique com o certificado de cliente X.509 + credenciais (clientId/clientSecret) e receba um token JWT. A validade do token vem no campo expires_in (em segundos): use esse valor para renovar o token antes de expirar, sem assumir um tempo fixo.
Autenticação (mTLS)
Esta rota exige mTLS: o certificado de cliente emitido pela Gateways é apresentado no handshake TLS, não em um header HTTP. Use o mecanismo nativo de certificado de cliente da sua biblioteca HTTP (por exemplo, curl --cert client.crt --key client.key).
- O certificado é PEM, RSA 2048, válido por 2 anos e vinculado à sua conta.
- O mTLS é exigido somente nesta rota. As demais rotas usam
Authorization: Bearer <token>, sem certificado.
Não envie o certificado em headers HTTP: esse modelo não é aceito. Sem o certificado no handshake, a API responde 400 com PUB_CERT_HEADER_MISSING.
Request Body
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
clientId | string (UUID v4) | Sim | Client ID gerado no painel (https://<dashboard-host>), em Configurações → Credenciais |
clientSecret | string | Sim | Client secret gerado junto com o clientId. É exibido uma única vez no painel. Não pode ser vazio |
{
"clientId": "6967c0a0-3566-48d0-8c13-717038b52279",
"clientSecret": "SEU_CLIENT_SECRET"
}Exemplo com cURL
curl -X POST https://<api-host>/api/auth/token \
--cert ./client.crt \
--key ./client.key \
-H "Content-Type: application/json" \
-d '{
"clientId": "SEU_CLIENT_ID",
"clientSecret": "SEU_CLIENT_SECRET"
}'Exemplos 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 em:', response.data.expires_in, 'segundos');A Gateways entrega o certificado em PEM (client.crt + client.key). Se a sua plataforma exige um arquivo .pfx/.p12 (comum em Java e em alguns ambientes Windows/.NET), converta localmente:
openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12A conversão é feita na sua máquina; a Gateways não fornece PFX.
Response (201)
| Campo | Tipo | Descrição |
|---|---|---|
access_token | string | Token JWT para o header Authorization: Bearer <token> |
token_type | string | Sempre Bearer |
expires_in | number | Validade do token em segundos. Renove antes de expirar com base neste valor |
scope | string | Escopo do token |
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "email profile"
}Erros
| Status | Código | Descrição |
|---|---|---|
| 400 | PUB_CERT_HEADER_MISSING | Certificado de cliente não apresentado no handshake TLS |
| 400 | PUB_CERT_MALFORMED_PEM | Certificado em formato PEM inválido |
| 400 | PUB_REQUEST_BODY_INVALID | Body inválido (ex.: clientId não é UUID v4, clientSecret vazio, campos extras). Os campos com problema vêm em details.violations |
| 401 | PUB_INVALID_CREDENTIALS | clientId/clientSecret inválidos |
| 401 | PUB_CERT_NOT_VERIFIED | Certificado não pôde ser verificado na conexão |
| 401 | PUB_CERT_NOT_REGISTERED | Certificado não cadastrado |
| 401 | PUB_CERT_EXPIRED | Certificado expirado |
| 401 | PUB_CERT_NOT_YET_VALID | Certificado ainda não está no período de validade |
| 403 | PUB_CERT_NOT_AUTHORIZED_FOR_ACCOUNT | Certificado não está vinculado à conta das credenciais |
| 502 | PUB_AUTH_UPSTREAM_ERROR | Erro inesperado no serviço de autenticação |
| 503 | PUB_AUTH_UPSTREAM_UNAVAILABLE | Serviço de autenticação temporariamente indisponível. Tente novamente |
{
"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 um guia completo de autenticação com padrões de renovação de token, veja Guia de Autenticação.