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

# Autenticação

> Bearer token, geração via POST /api-key/generate e boas práticas de segredo.

## Esquema

Rotas de negócio sob `/api/pix`, `/webhook`, `/organization`, entre outras, exigem:

```http theme={null}
Authorization: Bearer <seu_api_token>
```

Inclua também `Content-Type: application/json` em corpos `POST`/`PUT` quando aplicável.

## Obter credencial (geração de chave de API)

```bash theme={null}
curl -X POST https://api.clearpago.com.br/api-key/generate \
  -H "Authorization: Bearer <token_admin>" \
  -H "Content-Type: application/json"
```

**Resposta típica (200/201 — formato conforme implementação):**

```json theme={null}
{
  "apiKey": "ok_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2026-04-01T12:00:00Z"
}
```

O campo de token retornado é referido no guia de origem como `apiKey`; use-o como valor do **Bearer** nas chamadas subsequentes.

## Armazenamento e rotação

* Guarde o token em **segredo** (por exemplo, variável de ambiente ou cofre de credenciais).
* **Não** versionar o token em repositório.
* Evite logar o token em claro. Em vazamento ou suspeita de comprometimento, **gere novas chaves** e desative as antigas conforme o processo da sua operação.
* Toda a comunicação de produção deve ocorrer em **HTTPS** (TLS).

## Erros comuns

| HTTP  | Causa provável                                  | Ação                                         |
| ----- | ----------------------------------------------- | -------------------------------------------- |
| `401` | `Authorization` ausente ou inválido             | Conferir prefixo `Bearer ` e valor completo. |
| `401` | Token de admin incorreto em `/api-key/generate` | Revalidar o token administrativo.            |

Mensagens exatas e códigos adicionais: [Tratamento de erros](/errors/error-handling).

## Referência

* [Environments and headers](/getting-started/environments-and-headers) — códigos HTTP e envelope de erro.
* [Códigos de erro](/errors/error-codes) — troubleshooting ampliado.