Autenticação

A API do Sacador é autenticada por tokens portadores (Bearer tokens) emitidos pela conta.

Criando um token

1. Acesse /integrations → aba API e Webhook.
2. Na seção Tokens de API, dê um nome descritivo (ex.: ERP da empresa, Integração com loja virtual) e clique em Gerar token.
3. O token em texto puro será exibido uma única vez em um banner verde, com botão para copiar.
4. Guarde o valor em local seguro imediatamente. Não há como recuperá-lo depois — se você perder, terá que revogar e gerar um novo.

Formato do token

sct_<48 caracteres base58>

• Prefixo sct_ ("sacador token") — facilita identificar o tipo da credencial em logs e secret scanners.
• Comprimento total: 52 caracteres.
• Alfabeto: base58 (sem 0, O, I, l para evitar ambiguidade visual).

O que o Sacador armazena

Apenas o digest SHA256 do token e os 4 últimos caracteres (para exibir uma máscara como sct_••••••••XyZ9 na listagem). O texto puro não é persistido em banco, log ou backup. Por isso a única exibição acontece no momento da criação.

Usando o token nas requisições

Envie o token no header HTTP Authorization:

GET /v1/billings HTTP/1.1
Host: api.sacador.com.br
Authorization: Bearer sct_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Exemplo cURL (teste rápido para validar seu token — deve retornar 200 OK com a listagem ou 200 com lista vazia):

curl -X GET 'https://api.sacador.com.br/v1/billings?per_page=1' \
  -H 'Authorization: Bearer sct_seu_token_aqui'

Se receber 401, revise o header (deve começar com Bearer exatamente, com um espaço); se receber 403, o token foi revogado ou a conta está inativa.

Erros comuns:

Revogando um token

Em /integrations, na linha do token, clique em Revogar. A revogação:

• É imediata — todas as requisições subsequentes recebem 401.
• É definitiva — não há "des-revogar". Se precisar usar de novo, gere um token novo.
• Não afeta os outros tokens da conta.

O Sacador mantém um cache de autenticação de 15 minutos para reduzir consultas ao banco em rotas de alto volume. Esse cache é invalidado explicitamente no momento da revogação, então tokens revogados deixam de funcionar imediatamente — não há janela de tolerância.

Boas práticas

• Um token por sistema integrado. Se um sistema for comprometido, basta revogar o token correspondente sem afetar os outros.
• Rotação periódica. Crie um token novo, atualize o sistema integrado, depois revogue o antigo.
• Nunca commite o token no código-fonte. Use variáveis de ambiente, gerenciadores de secret (Vault, AWS Secrets Manager, etc.) ou o sistema de credentials do seu framework.
• Monitore o uso dos tokens no seu lado: requisições inesperadas podem indicar que o token vazou.

Diferença entre token de API e secret de webhook

São coisas diferentes, com propósitos opostos: