Autenticação
Chaves de API: como usar, guardar e trocar.
Toda chamada à API usa uma chave de API no cabeçalho Authorization:
Authorization: Bearer ssk_<prefixo>_<segredo>
Como a chave funciona#
- A chave pertence a um cliente (a sua conta). Os dados de um cliente nunca aparecem para outro: o
tokende sessão de outro cliente responde404 token_not_found. - Só o hash da chave fica guardado no servidor. Ela é exibida uma única vez, ao ser criada. Se você perdê-la, revogue e crie outra.
- Chave ausente, errada ou revogada:
401 unauthorized. Cliente suspenso:403 tenant_suspended. - Revogar uma chave ou suspender um cliente vale na API em até 15 segundos.
Criar e revogar chaves#
No painel, em Painel de Controle → Tokens de acesso à API. Dê um nome que diga onde a chave é usada (por exemplo, producao e homologacao), para poder revogar uma sem afetar a outra. Veja Usando o painel.
Regras que não mudam#
- A chave fica só no seu servidor. Nunca em JavaScript de navegador, aplicativo móvel ou repositório de código.
- O navegador nunca fala com a API. Ele fala com o seu servidor, e o seu servidor fala com a API.
- O PIN do token é digitado só na janela da extensão. O seu código nunca o vê.
- Trate a chave como senha: variável de ambiente ou cofre de segredos, uma chave por ambiente, e troca periódica ou imediata em caso de suspeita de vazamento.
Vazou uma chave?
Revogue-a no painel imediatamente e crie outra. A revogação vale em até 15 segundos. Depois, revise a atividade da conta no painel.
Identificação das chamadas#
Toda resposta traz o cabeçalho X-Request-Id. Registre-o junto dos seus erros: com ele a equipe encontra a chamada exata ao atender você. Veja Suporte.
Limites por minuto#
Cada cliente tem um limite de requisições por minuto, definido no plano. Ao passar, a API responde 429 rate_limited com o cabeçalho Retry-After (em segundos): espere esse tempo antes de tentar de novo. Veja Limites e cotas.