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

# API Key

> Como gerar e usar sua API Key

A **API Key** é a forma de autenticação para chamadas server-to-server do `ConsentFly`. Cada chave é única, associada à sua conta, e pode ser gerada no painel após o login.

## Como obter sua API Key

1. Acesse [www.consentfly.com.br](https://www.consentfly.com.br) e faça login.
2. No menu lateral abra **API Keys**.
3. Clique em **Gerar nova chave** e copie o valor imediatamente.

A chave é exibida apenas uma vez, no formato:

```text theme={null}
sk-rQiYxSxAdIvJpemBGWnxoemdgyHIWQxs
```

> **Atenção:** a chave equivale a uma senha. Nunca a coloque em código de frontend, repositórios públicos ou logs.

## Como usar a API Key

Envie a chave no header `Authorization`, prefixada por `Bearer`:

```http theme={null}
GET /api/v1/consents?site_id=<site_uuid> HTTP/1.1
Host: www.consentfly.com.br
Authorization: Bearer sk-rQiYxSxAdIvJpemBGWnxoemdgyHIWQxs
```

### Endpoints que aceitam API Key (e cota)

Documentação narrativa:

* [API de consentimentos](./consents-api) — CRUD, batch, recibo, DSAR
* [Exportar consentimentos](./exports-api) — CSV streaming + jobs async
* [Webhooks](./webhooks) — lado consumidor (verificação de assinatura)

Referência OpenAPI completa: aba **API Reference**.

| Família                   | Endpoints                                                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Consents (CRUD + history) | `POST /consents`, `GET /consents`, `GET /consents/{id}`, `PUT /consents/{id}`, `DELETE /consents/{id}`, `GET /consents/{id}/history`     |
| Batch                     | `POST /consents/batch`                                                                                                                   |
| DSAR                      | `GET /consents/{id}/receipt`, `DELETE /consents/by-subject/{subjectId}`                                                                  |
| Exports                   | `GET /sites/{siteId}/consents/export`, `POST /sites/{siteId}/exports`, `GET /exports`, `GET /exports/{id}`, `GET /exports/{id}/download` |

Todas estas rotas aceitam `Bearer sk-...` e descontam **1** unidade da cota mensal por chamada bem-sucedida (a primeira linha de um batch é coberta pela cobrança do request; as demais somam +1 cada).

**Gerenciamento de webhooks** (criar, editar, desabilitar, replay de deliveries falhadas) é feito apenas pelo dashboard — não há rotas API-key para essa CRUD ainda.

## Cota e plano

Cada requisição **`/consents`** autenticada com **API Key** consome **1** unidade da cota mensal. Chamadas ao mesmo endpoint feitas pelo próprio dashboard (sessão autenticada) não incrementam esse contador.

| Plano      | Sites máximos | Requisições API / mês |
| ---------- | ------------: | --------------------: |
| Free       |             1 |                   100 |
| Starter    |             5 |                20.000 |
| Pro        |            20 |                50.000 |
| Enterprise |   customizado |           customizado |

Quando você ultrapassar o limite a API responde `429 Too Many Requests` com o código `quota_exceeded`. O contador é renovado conforme o período de uso da API (mensal).

Além da cota mensal, endpoints sensíveis aplicam **rate-limit por IP** em janela curta — se bater, o erro vem como `too_many_requests`. Espalhe as chamadas com pequeno jitter ou bloqueio em backoff exponencial para evitá-lo.

## Boas práticas

* Use chaves diferentes por ambiente (dev, staging, produção).
* Revogue chaves antigas pelo painel sempre que possível.
* Monitore o erro `unauthorized` — ele significa que a chave foi revogada ou que a conta está com `plan_status` não-ativo.

<p align="center">
  Dúvidas? Fale com a gente em <a href="mailto:suporte@consentfly.com.br">[suporte@consentfly.com.br](mailto:suporte@consentfly.com.br)</a>
</p>