Visão geral
Os dois modos de autenticar na API White Label: senha do cliente final e Tenant API Key.
Toda chamada autenticada da API White Label usa um JWT no header Authorization, sempre
acompanhado do X-Tenant-Id. O que muda é como você obtém esse JWT — e existem dois
caminhos.
Os dois modos
POST /authenticate | POST /authenticate/clients | |
|---|---|---|
| Credencial | senha do cliente final | Tenant API Key (tnk_…) |
| Onde vai | corpo da requisição | header X-Tenant-Api-Key |
| Quem usa | app / internet banking do cliente final | backend do tenant (server-to-server) |
| Validade do JWT | 1 hora | 24 horas |
| Escopo | só o cliente que fez login | um cliente por chamada, escolhido pelo CPF/CNPJ |
Use o login com senha quando quem está do outro lado é o cliente final: ele digita CPF/CNPJ e senha no seu app ou IB. É o fluxo de sempre.
Use a Tenant API Key quando é o seu backend que precisa operar em nome dos seus clientes — conciliação diária, robô de pagamentos, painel interno. Você informa só o CPF/CNPJ do titular e recebe o JWT dele, sem precisar armazenar a senha de ninguém.
Obtendo um token com a Tenant API Key
curl -X POST https://baas.staterpay.io/authenticate/clients \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "X-Tenant-Id: 00000000-0000-0000-0000-000000000000" \-H "X-Tenant-Api-Key: tnk_0356d4a1.vsqBAy5sAI63nyUoxgN-NWVfmIFdX9W6" \-d '{ "document": "12345678900" }'A resposta tem o mesmo shape do POST /authenticate — veja
Autenticação (API Key) para a referência
completa de campos e erros.
A chave
A Tenant API Key é a credencial de serviço do seu white label, no formato
tnk_<prefixo>.<segredo>. Ela é emitida pelo backoffice — não há self-service. Solicite ao
seu contato comercial ou ao suporte.
Você recebe o segredo uma única vez, na emissão: depois ele só existe como hash, não há como recuperar. Guarde em um cofre de segredos (Vault, AWS Secrets Manager, etc.).
Com ela é possível autenticar como qualquer titular do seu tenant. Trate-a como senha de root: uso exclusivamente server-to-server, nunca em app mobile, front-end, log ou repositório. Cada login feito com a chave fica auditado (chave, IP, documento e horário).
Validade e renovação
O JWT emitido em /authenticate/clients vale 24 horas e é restrito ao titular
informado. Para operar vários titulares, repita a chamada com o documento de cada um — um
token por titular, cacheável até expirar.
Na prática isso é uma re-autenticação por titular por dia. Trate 401 re-chamando
/authenticate/clients: como a credencial é a chave (e não uma senha de pessoa), a
renovação é automática e não depende de ninguém.
Revogação e rotação
Se uma chave for revogada — a seu pedido ou por decisão da plataforma — todos os tokens
emitidos com ela param de funcionar imediatamente, mesmo os que ainda estavam dentro das
24 horas. As requisições passam a receber 401.
Rotação recomendada: solicite uma chave nova, migre o seu sistema e só então revogue a antiga — as duas coexistem durante a transição. Em caso de suspeita de vazamento, peça a revogação na hora: os tokens em circulação morrem junto com a chave.
PIN nas operações de escrita
Por padrão, movimentações (Pix, TEV) exigem o pin do cliente final no corpo da requisição
mesmo autenticado por Tenant API Key — o titular precisa autorizar.
Se as chamadas server-to-server do seu sistema precisarem dispensar o PIN, solicite ao suporte a ativação da opção Isenção de PIN via API de Tenant para o seu tenant. Com ela ativa, apenas as requisições autenticadas por Tenant API Key ficam isentas; os acessos dos seus clientes pelo app ou IB continuam exigindo o PIN normalmente.
Erros de autenticação
400—X-Tenant-Idausente ou inválido, oudocumentfora de 11–14 dígitos.401— chave ausente, inválida, revogada, expirada ou de outro tenant; documento que não corresponde a um titular do seu tenant; ou titular bloqueado.429— rate limit excedido.