> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

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.

```text theme={null}
ApiKey: your_api_key_here
```

Se o cabeçalho estiver ausente, escrito incorretamente ou contiver uma chave inválida, a API retornará um erro. Veja [solução de problemas](#solução-de-problemas).

**Exemplo de requisição**

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/info?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'
```

**Para endpoints POST**, inclua também `Content-Type`:

```bash theme={null}
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"query": "bitcoin", "order": "popular"}'
```

> **Dica:** teste sua chave sem escrever código no [API Playground](https://api.sorsa.io/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](https://docs.sorsa.io/pt-BR/api-reference-guide).

## Gerencie suas chaves

**Encontre sua chave.** Ela aparece na [visão geral do painel](https://api.sorsa.io/overview). 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](https://api.sorsa.io/overview/keys).

**Monitore o consumo.** Consulte o histórico e a cota restante em [Usage stats](https://api.sorsa.io/overview/usage) 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](https://api.sorsa.io/overview/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](https://api.sorsa.io/overview) 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](https://docs.sorsa.io/pt-BR/rate-limits).

**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

* [Limites de requisições](https://docs.sorsa.io/pt-BR/rate-limits): cotas e novas tentativas.
* [Consumo da chave](https://docs.sorsa.io/pt-br/api-reference/utilit%C3%A1rios/uso-da-chave-de-api): consulte o saldo programaticamente.
* [Referência da API](https://docs.sorsa.io/pt-BR/api-reference-guide): endpoints disponíveis.