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

# Autenticação

> Como autenticar suas requisições, tipos de chave e boas práticas de segurança.

A API Simplo usa **chaves de API** enviadas no header `Authorization`. Não há OAuth nem tokens de acesso curtos — uma chave por conta, válida até você revogar.

## Formato

```http theme={null}
Authorization: ApiKey live_a1B2c3D4e5F6...
```

<Warning>
  O prefixo no header é `ApiKey ` (com espaço), **não** `Bearer`. Esse é o erro mais comum em integrações novas.
</Warning>

## Tipos de chave

A própria chave começa com um prefixo que indica o ambiente:

<CardGroup cols={2}>
  <Card title="Sandbox (teste)" icon="flask">
    Prefixo `test_`. Toda cobrança é simulada — nada é cobrado de verdade. Use no desenvolvimento e em CI.
  </Card>

  <Card title="Produção (live)" icon="rocket">
    Prefixo `live_`. Cobrança real, com gateway real. Trate como senha.
  </Card>
</CardGroup>

A chave completa tem o formato `{prefixo}_{token}`, onde o token é uma sequência aleatória codificada em base62. Exemplo: `live_3a7f9e2c1b5d8a4f...`.

## Como gerar e revogar

<Steps>
  <Step title="Acesse o painel">
    Entre em [besimplo.com](https://besimplo.com) e abra **Configurações → Chaves de API**.
  </Step>

  <Step title="Gere uma nova chave">
    Dê um nome descritivo (ex.: `produção-backend`, `staging-app`). A chave aparece **uma única vez** — copie e guarde.
  </Step>

  <Step title="Revogue chaves antigas">
    Quando trocar de servidor, vazar uma chave ou desligar uma integração, revogue. A revogação é imediata.
  </Step>
</Steps>

## Onde guardar

<Tip>
  **Nunca** comite chaves no Git. Use variáveis de ambiente ou um cofre de segredos.
</Tip>

```bash theme={null}
# .env (não comite este arquivo)
SIMPLO_API_KEY=live_xxxxxxxxxxxxxxxx
```

```ruby theme={null}
# Ruby
api_key = ENV.fetch("SIMPLO_API_KEY")
```

```javascript theme={null}
// Node.js
const apiKey = process.env.SIMPLO_API_KEY;
```

## Rate limits

A API limita requisições **por chave de API** para evitar abuso e manter estabilidade:

| Operação                         | Limite         |
| -------------------------------- | -------------- |
| Criação (POST)                   | 10 por minuto  |
| Leitura/atualização (GET, PATCH) | 100 por minuto |

Quando você ultrapassa, recebe `429 Too Many Requests`. [Veja como tratar erros 429](/conceitos/erros#rate-limit-429).

## Vazei minha chave. E agora?

<Steps>
  <Step title="Revogue imediatamente">
    Painel → **Configurações → Chaves de API** → revogar.
  </Step>

  <Step title="Gere uma nova">
    Substitua a chave em todos os ambientes que dependem dela.
  </Step>

  <Step title="Audite o uso recente">
    Verifique no painel se houve atividade suspeita entre o vazamento e a revogação. Em caso de cobranças indevidas, fale com o suporte: [team@besimplo.com](mailto:team@besimplo.com).
  </Step>
</Steps>