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

# Autenticação

> Como autenticar suas requisições usando API Keys.

## Visão Geral

Todas as requisições à API Campeão Sec precisam ser autenticadas com uma **API Key** enviada no header `Authorization`.

```http theme={null}
Authorization: Bearer sk_live_sua_chave_aqui
```

***

## Tipos de API Key

| Prefixo    | Ambiente | Quando usar                                 |
| ---------- | -------- | ------------------------------------------- |
| `sk_live_` | Produção | Verificações reais, créditos debitados      |
| `sk_test_` | Sandbox  | Testes e integração, sem débito de créditos |

As chaves são geradas e gerenciadas no portal em **app.campeaosec.com → API Keys**.

***

## Como Gerar uma Chave

1. Acesse **app.campeaosec.com**
2. No menu lateral, clique em **API Keys**
3. Clique em **Nova chave**
4. Selecione o ambiente (Sandbox ou Produção)
5. Copie a chave gerada — ela é exibida **apenas uma vez**

<Warning>
  Guarde a chave em um local seguro. Após fechar o modal, não é possível recuperar o valor completo — apenas os últimos caracteres serão exibidos.
</Warning>

***

## Sandbox vs Produção

| Comportamento                 | Sandbox | Produção |
| ----------------------------- | ------- | -------- |
| Créditos debitados            | Não     | Sim      |
| Webhook disparado             | Sim     | Sim      |
| Magic CPFs de teste           | Sim     | Não      |
| Processamento real de imagens | Não     | Sim      |

Use sempre `sk_test_` durante o desenvolvimento. A chave de produção só deve estar no servidor — nunca no frontend ou app mobile.

***

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-kyc.campeaosec.com/v1/verify/session \
    -H "Authorization: Bearer sk_test_sua_chave_aqui" \
    -H "Content-Type: application/json" \
    -d '{"country": "BR", "external_id": "user-123", "ambiente": "sandbox"}'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api-kyc.campeaosec.com/v1/verify/session', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_sua_chave_aqui',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      country: 'BR',
      external_id: 'user-123',
      ambiente: 'sandbox',
    }),
  })
  const data = await res.json()
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api-kyc.campeaosec.com/v1/verify/session',
      headers={
          'Authorization': 'Bearer sk_test_sua_chave_aqui',
          'Content-Type': 'application/json',
      },
      json={
          'country': 'BR',
          'external_id': 'user-123',
          'ambiente': 'sandbox',
      }
  )
  data = response.json()
  ```
</CodeGroup>

***

## Erros de Autenticação

| Código HTTP | Detalhe          | Causa                                                         |
| ----------- | ---------------- | ------------------------------------------------------------- |
| `401`       | `unauthorized`   | Chave ausente, inválida ou revogada                           |
| `403`       | `key_inactive`   | Chave desativada no portal                                    |
| `403`       | `wrong_ambiente` | Usando chave `sk_live_` com `ambiente: sandbox` ou vice-versa |