Skip to main content
A Sorsa API usa chaves de API para autenticar requisições. Sua chave dá acesso à conta e à cota; trate-a como uma senha.

​
Como funciona a autenticação

Toda requisição deve incluir a chave no cabeçalho ApiKey. Nomes de cabeçalhos HTTP não diferenciam maiúsculas de minúsculas; use a grafia abaixo e preserve o valor da chave exatamente.
Se o cabeçalho estiver ausente, escrito incorretamente ou contiver uma chave inválida, a API retornará um erro. Veja solução de problemas. Exemplo de requisição
Para endpoints POST, inclua também Content-Type:
Dica: teste sua chave sem escrever código no API Playground.

​
Requisitos das requisições

Somente HTTPS. Todas as requisições devem usar https://. HTTP sem criptografia será rejeitado. Cabeçalho ApiKey. Obrigatório em todas as requisições. A autenticação não usa OAuth, tokens bearer ou parâmetros de consulta. Cabeçalho Content-Type. Obrigatório em POST. Use application/json e envie os parâmetros no corpo JSON. Métodos HTTP. Os endpoints usam GET ou POST. Consulte o método de cada um na referência da API.

​
Gerencie suas chaves

Encontre sua chave. Ela aparece na visão geral do painel. Contas novas incluem 100 requisições gratuitas, sem cartão de crédito. Crie ou exclua chaves. Gere uma chave ou revogue uma existente na seção API Keys. Monitore o consumo. Consulte o histórico e a cota restante em Usage stats ou pelo endpoint GET /key-usage-info.
Importante: ao excluir ou substituir uma chave, aplicações que usam a chave antiga passam a receber 401 Unauthorized imediatamente. Atualize as integrações antes de revogar a chave.

​
Boas práticas de segurança

Nunca exponha a chave no cliente. Não chame a Sorsa diretamente de navegadores, aplicativos móveis ou frontend. A chave ficaria visível em ferramentas de desenvolvedor, logs de rede e código-fonte. Encaminhe as requisições pelo seu backend. Use variáveis de ambiente. Armazene a chave em arquivos .env ou no gerenciador de segredos da plataforma, como AWS Secrets Manager, Vercel Environment Variables ou Railway Variables. Não coloque chaves diretamente no código. Não versione chaves. Adicione .env ao .gitignore. Não faça commits com chaves em repositórios públicos ou privados no GitHub, GitLab ou Bitbucket. Substitua chaves comprometidas imediatamente. Se expuser uma chave em um commit, captura de tela ou fórum, acesse API Keys, exclua-a e gere outra. A chave antiga para de funcionar imediatamente.

​
Solução de problemas

401 Unauthorized O cabeçalho está ausente, incorreto ou a chave foi excluída ou nunca foi válida. Use ApiKey, não Api-Key ou Authorization. 403 Forbidden A chave é válida, mas a assinatura expirou ou a cota mensal acabou. Consulte o saldo no painel ou em GET /key-usage-info. 429 Too Many Requests Você ultrapassou o limite de 20 requisições por segundo. Adicione uma espera entre chamadas e tente novamente. Veja limites de requisições. Erros de CORS no navegador Você provavelmente está chamando a API pelo frontend. A Sorsa foi projetada para uso no servidor. Mova as chamadas para um serviço de backend ou uma função serverless.

​
Próximos passos