Autenticação
Toda chamada vai com a chave no header Authorization. Sem header, com header malformado ou com chave desconhecida: 401.
bash
curl "https://public-api.passkey.global/v1/sales" \
-H "Authorization: Bearer passkey_prd_SEU_SEGREDO_AQUI"Como conseguir a chave
- A chave sai da seção Chaves de API, em Configurações — a própria tela gera.
- O segredo aparece uma vez só. Guarde na hora — nós armazenamos apenas o hash dela, então não existe "mostrar de novo". Perdeu, revogue e gere outra.
Você pode ter 2 chaves ativas ao mesmo tempo. São duas de propósito: é o que permite trocar a chave em produção sem janela sem acesso — cria a nova, troca no seu sistema, revoga a velha.
Validade da chave
Na hora de criar, você escolhe por quanto tempo a chave vale: 1 dia, 30 dias, 90 dias ou permanente. A escolha é feita uma vez e não muda depois — para trocar o prazo, gere outra chave e revogue esta.
- 1, 30 ou 90 dias — a chave para de valer na data e passa a devolver
401API_KEY_EXPIRED. A data de vencimento aparece na listagem de chaves. - Permanente — sem data de vencimento. Ela só para quando você revogar.
Permanente não é eterna: chave sem uso há mais de 90 dias é revogada automaticamente. Chave nunca usada conta a partir da criação. Se a sua integração consulta a API de tempos em tempos, isso nunca te alcança.
Escopos
A chave carrega escopos, e a rota exige o dela. Chave autenticada mas sem o escopo necessário devolve 403, não 401 — a diferença importa, porque 401 pede outra credencial e 403 pede outra permissão.
| Escopo | Dá acesso a |
|---|---|
tracking:read | as três rotas de leitura do /v1 |
tracking:write | reservado; nenhuma rota pública o usa hoje |
Quando a chave para de funcionar
| Situação | Resposta |
|---|---|
| Chave revogada na tela | 401 API_KEY_REVOKED |
| Chave expirada | 401 API_KEY_EXPIRED |
| Conta bloqueada, inadimplente ou removida | 401 / 403, conforme o caso |
| Escopo insuficiente | 403 API_KEY_SCOPE_DENIED |
Revogar tem efeito imediato: não há cache de permissão entre a revogação e a próxima chamada.
Cuidados
- A chave identifica a conta inteira. Trate como senha: variável de ambiente ou cofre, nunca no código-fonte, nunca em repositório.
- Ela dá acesso de leitura ao histórico de vendas. Não a use em frontend — qualquer visitante leria o header.
- Suspeita de vazamento: revogue na tela. A chave morre na hora e o restante da conta segue intacto.
O limite é de 120 requisições por minuto, por chave. O contador é por chave, não por IP.