> ## 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.

# Criar Sessão Auth

> Inicie uma sessão de autenticação biométrica e obtenha o token para o widget.

## Visão Geral

O fluxo Auth 1:1 valida que a pessoa que está operando o dispositivo é a mesma que realizou o KYC anteriormente. O embedding facial armazenado no KYC é usado como referência — nenhum dado biométrico novo precisa ser cadastrado.

```
Seu servidor                Widget (frontend do usuário)
    │                               │
    │── POST /v1/auth/session ────► API Campeão Sec
    │◄── { session_token } ─────────│
    │                               │
    │── session_token ─────────────►│
    │                    CampeaoSecAuth.init({ sessionToken })
    │                               │◄── selfie com liveness
    │                               │◄── webhook auth.completed → seu servidor
```

<Note>
  O usuário precisa ter passado por KYC com `approved` antes de poder ser autenticado. A Campeão Sec usa o embedding facial do KYC como template de comparação.
</Note>

***

## Endpoint

```
POST https://api-kyc.campeaosec.com/v1/auth/session
```

***

## Request

### Headers

| Header          | Valor                                        |
| --------------- | -------------------------------------------- |
| `Authorization` | `Bearer sk_test_...` ou `Bearer sk_live_...` |
| `Content-Type`  | `application/json`                           |

### Body

| Campo          | Tipo   | Obrigatório | Descrição                                                                                                     |
| -------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `external_id`  | string | **Sim**     | ID do usuário no seu sistema. Deve corresponder ao `external_id` usado no KYC. Max 255 chars                  |
| `webhook_url`  | string | Não         | URL para receber `auth.completed`. Sobrescreve a URL configurada no portal                                    |
| `redirect_uri` | string | Não         | Deep link para retorno em apps nativos (ex: `meuapp://auth-complete`). Deve ser um URI scheme, não HTTP/HTTPS |
| `ambiente`     | string | Não         | `sandbox` ou `producao`. Default: `sandbox`                                                                   |

***

## Response

```json theme={null}
{
  "session_token": "b7e2a1f9c3d8...",
  "expira_em": "2026-07-31T10:15:00Z"
}
```

Quando `redirect_uri` está presente, a resposta inclui também `widget_url`:

```json theme={null}
{
  "session_token": "b7e2a1f9c3d8...",
  "widget_url": "https://api-kyc.campeaosec.com/widget?auth_token=b7e2a1f9c3d8...",
  "expira_em": "2026-07-31T10:15:00Z"
}
```

| Campo           | Tipo           | Descrição                                                              |
| --------------- | -------------- | ---------------------------------------------------------------------- |
| `session_token` | string         | Token de 64 caracteres para inicializar o widget de autenticação       |
| `widget_url`    | string \| null | URL completa do widget (retornada quando `redirect_uri` está presente) |
| `expira_em`     | string         | Data/hora de expiração (ISO 8601). A sessão expira em **15 minutos**   |

<Warning>
  O `session_token` expira em 15 minutos — mais curto que o KYC intencionalmente, pois autenticações são operações sensíveis. Gere imediatamente antes de abrir o widget.
</Warning>

***

## Exemplos

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-kyc.campeaosec.com/v1/auth/session \
    -H "Authorization: Bearer sk_test_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "external_id": "user-456",
      "ambiente": "sandbox",
      "webhook_url": "https://seu-servidor.com/webhook/auth"
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api-kyc.campeaosec.com/v1/auth/session', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_sua_chave',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      external_id: 'user-456',
      ambiente: 'sandbox',
      webhook_url: 'https://seu-servidor.com/webhook/auth',
    }),
  })
  const { session_token, expira_em } = await res.json()

  // Passe session_token para o frontend via sua API interna
  ```

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

  response = requests.post(
      'https://api-kyc.campeaosec.com/v1/auth/session',
      headers={
          'Authorization': 'Bearer sk_test_sua_chave',
          'Content-Type': 'application/json',
      },
      json={
          'external_id': 'user-456',
          'ambiente': 'sandbox',
          'webhook_url': 'https://seu-servidor.com/webhook/auth',
      }
  )
  data = response.json()
  session_token = data['session_token']
  ```
</CodeGroup>

***

## Consultar Resultado (Fallback)

Se o webhook não chegar, consulte o resultado diretamente pelo `auth_id` retornado no `onSuccess` do widget:

```bash theme={null}
curl -X GET https://api-kyc.campeaosec.com/v1/auth/{auth_id} \
  -H "Authorization: Bearer sk_test_sua_chave"
```

***

## Erros

| Código | Detalhe                | Causa                                                |
| ------ | ---------------------- | ---------------------------------------------------- |
| `401`  | `unauthorized`         | API Key inválida                                     |
| `402`  | `insufficient_credits` | Saldo de créditos Auth zerado (produção)             |
| `403`  | `auth_module_disabled` | Módulo Auth 1:1 não ativo para sua conta             |
| `404`  | `no_embedding_found`   | Nenhum embedding KYC encontrado para o `external_id` |
| `422`  | `invalid_redirect_uri` | `redirect_uri` deve ser um deep link, não HTTP/HTTPS |
| `422`  | `invalid_ambiente`     | Deve ser `sandbox` ou `producao`                     |