Autenticação

Troque clientId e clientSecret por um token bearer no servidor e renove-o antes de expirar.

Ciclo do token

1clientId + clientSecret (só no servidor)

2 │ POST /resource/auth/token

3 ▼

4accessToken, válido por expiresIn

5 │ Authorization: Bearer <token>

6 ▼

7emita outro pouco antes de expirar

Emissão do token

POST /resource/auth/token é a única operação pública. Ela recebe clientId e clientSecret e devolve o token em data.accessToken:

2 "error": false,

3 "message": "Token generated successfully",

4 "data": {

5 "accessToken": "<token>",

6 "tokenType": "Bearer",

7 "expiresIn": 1800

8 },

9 "pagination": null

10}

expiresIn é a validade em segundos (hoje, 30 minutos). Guarde o token em memória no servidor e emita um novo pouco antes de expirar, em vez de pedir um token a cada chamada.

Uso do token

Envie o token em todas as demais operações:

1Authorization: Bearer <seu-token>

O token identifica a sua organização e as permissões da credencial. Por isso as operações Pix não recebem organizationId, e só enxergam carteiras e transações da sua organização e das suborganizações dela.

O header x-customer-id, que aparece em algumas operações, é opcional: a API atual não o lê.

Respostas de erro

Status	Significado	O que fazer
`400`	`clientId` ou `clientSecret` ausentes	Corrija o corpo
`401` na emissão	Credencial inválida ou revogada	Não repita em laço; confira a credencial
`401` em outra operação	Token ausente ou inválido; veja abaixo o caso de token expirado	Emita um novo token e repita uma única vez
`403`	Token válido, sem a permissão exigida	Não repita; solicite a permissão
`429`	Limite de tentativas	Aguarde e tente com espera progressiva

Hoje, um token expirado pode receber 503 com type terminado em auth-provider-unavailable, em vez de 401. Renove o token antes de expiresIn e, se receber esse 503, emita um token novo antes de repetir a chamada. Se a chamada movimenta dinheiro, siga a regra de Repetição segura em Erros e respostas antes de repetir.

Segurança

nunca envie o clientSecret ou o token ao navegador;
não grave credenciais ou tokens em logs;
use TLS em todas as chamadas;
não exponha ao usuário final os detalhes de um 401;
rotacione a credencial conforme o processo da sua organização.