API tokens

A API ValePix usa API tokens opacos no padrão Bearer token. O cliente recebe o token completo uma única vez por canal seguro e deve armazená-lo como segredo.

Como autenticar chamadas

Envie o token somente no header Authorization:

Authorization: Bearer <VALEPIX_API_TOKEN>

Exemplo:

curl --request GET \
  --url "https://routes.valepix.com.br/api/v1/valepix/employees/situations" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Não envie o token em query string, corpo da requisição, planilhas, tickets públicos ou logs.

Validação do token

Use um API token autorizado para acessar as rotas públicas de benefícios, colaboradores e lotes.

Na prática, uma chamada precisa passar por duas verificações:

1. O token existe, está ativo e não expirou.
2. O token tem acesso ao recurso solicitado.

Erros comuns de autenticação

HTTP	Causa provável	Ação recomendada
401	Token ausente, inválido, expirado ou revogado	Conferir header e solicitar novo token se necessário
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix

Exemplo de token revogado:

{
  "error": "token_revoked"
}

Boas práticas de segurança

• Armazene o token em secret manager, cofre de credenciais ou variável segura do ambiente.
• Restrinja acesso ao token somente aos serviços que chamam a API.
• Nunca registre o token completo em logs de aplicação, observabilidade ou auditoria.
• Mascare tokens em telas internas, exibindo no máximo um prefixo não sensível.
• Use HTTPS sempre.
• Rotacione o token periodicamente ou quando houver suspeita de exposição.
• Revogue o token quando a integração for desativada.

Informações recebidas da ValePix

O cliente deve receber:

• Base URL da API.
• API token completo, entregue uma única vez.
• Exemplos de payload e IDs necessários para a integração, quando aplicável.