Autenticação

A Partner API usa o fluxo OAuth2 client_credentials (RFC 6749, seção 4.4). O parceiro troca o seu client_id e o seu client_secret por um token Bearer de curta duração e usa esse token em todas as demais chamadas.

Obter o token

POST /api/partner/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}

O endpoint também aceita corpo application/json.

O IP de origem precisa pertencer à lista IPv4/IPv6 cadastrada na própria credencial. A lista é obrigatória, redes /0 não são aceitas e a validação ocorre tanto na emissão do token quanto em cada chamada Bearer. Alterar a lista afeta imediatamente inclusive os tokens já emitidos.

Resposta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 28800,
  "scope": "account:read pix:write"
}

• expires_in é o tempo de validade em segundos (8 horas).
• scope é a interseção dos escopos solicitados com as permissões da credencial.

Usar o token

Envie o token em todas as chamadas seguintes:

Authorization: Bearer {{access_token}}

Quando o token expirar, basta solicitar um novo em POST /api/partner/v1/oauth/token.

Verifique a credencial

Depois de obter o token, confirme a integração com uma chamada de sanidade:

GET /api/partner/v1/ping
Authorization: Bearer {{access_token}}

{ "status": "ok", "partner_id": 42 }

O endpoint aceita qualquer token de parceiro válido e ecoa o partner_id da credencial, para confirmar que ela está ativa e apontando para o parceiro esperado.

Respostas de erro do token

HTTP	error	Quando ocorre
400	invalid_request	Falta grant_type, client_id ou client_secret
400	unsupported_grant_type	grant_type diferente de client_credentials
401	invalid_client	Falha de autenticação da credencial ou da sua origem de rede

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Segurança

• Guarde o client_secret em local seguro. Nunca o exponha em código versionado, front-end ou logs.
• O token tem validade curta; solicite um novo sempre que necessário.
• Cadastre ao menos uma origem IPv4/IPv6 restritiva na credencial; listas vazias e redes /0 bloqueiam o acesso.
• Não dependa de um token já emitido para manter acesso depois de uma rotação de rede ou revogação da chave.