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

# Autenticação

> Como gerar e usar sua API key, escopos e versionamento

## Gerar uma API key

1. Acesse **Integrações & API → API Keys** no [dashboard kycert](https://admin.kycert.com.br)
2. Clique em **Nova chave**
3. Dê um nome descritivo (ex: "Integração onboarding prod")
4. Selecione os escopos necessários (ver tabela abaixo)
5. Copie a chave imediatamente — **ela não é exibida novamente**

<Warning>
  Nunca exponha a API key no frontend, em repositórios públicos ou em logs. Armazene-a como variável de ambiente.
</Warning>

## Escopos

| Escopo        | Permite                                                   |
| ------------- | --------------------------------------------------------- |
| `runs:write`  | Criar runs (`POST /bureau/runs`)                          |
| `runs:read`   | Ler status, análise e listar runs                         |
| `detail:read` | Detalhes técnicos por fonte — requer aprovação do suporte |

Crie chaves com o mínimo de escopos necessários. Para onboarding automatizado, `runs:write` é suficiente. Para consulta de histórico, adicione `runs:read`.

## Como autenticar

Inclua a API key em **um** dos dois formatos:

```bash theme={null}
# Recomendado: header x-api-key
curl -H "x-api-key: sk_live_..." https://admin.kycert.com.br/api/v1/bureau/runs

# Alternativo: Authorization: Bearer
curl -H "Authorization: Bearer sk_live_..." https://admin.kycert.com.br/api/v1/bureau/runs
```

Ambos são equivalentes. O header `x-api-key` é mais simples e recomendado.

## Versionamento da API

Inclua o header `x-kycert-api-version` para fixar a versão e evitar breaking changes:

```bash theme={null}
curl -H "x-api-key: sk_live_..." \
     -H "x-kycert-api-version: 2026-06-03" \
     https://admin.kycert.com.br/api/v1/bureau/runs
```

* **Omitir** o header = versão mais recente (pode receber breaking changes)
* **Fixar em `2026-06-03`** = versão estável garantida por pelo menos 12 meses após depreciação

<Info>
  Versão atual: **2026-06-03**. Veja o [changelog](/changelog) para histórico de versões.
</Info>

## Sandbox

Use uma chave `sk_test_...` para desenvolvimento. Sandbox:

* Usa os mesmos endpoints de produção
* Retorna dados fictícios baseados em CPFs/CNPJs de teste
* Não gera cobrança
* Comportamento da API é idêntico ao de produção

Consulte a [tabela de CPFs e CNPJs de teste](/sandbox).

## Segurança

* **Rotação de keys**: crie uma nova key, atualize seu sistema, revogue a antiga
* **Revogação**: Integrações & API → API Keys → Revogar (imediato)
* **Nunca** use `sk_live_` em ambientes de desenvolvimento — crie uma `sk_test_`
* **Nunca** inclua a key diretamente no código — use variáveis de ambiente

```bash theme={null}
# Correto
export KYCERT_API_KEY="sk_live_..."

# Errado — não faça isso
const API_KEY = "sk_live_..."  // hardcoded no código
```