Criar Sessão Auth

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

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.

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

{
  "session_token": "b7e2a1f9c3d8...",
  "expira_em": "2026-07-31T10:15:00Z"
}

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

{
  "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

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.

Exemplos

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"
  }'

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

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']

Consultar Resultado (Fallback)

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

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`

Primeiros Passos

KYC Verify

Auth 1:1

Visão Geral

Endpoint

Request

Headers

Body

Response

Exemplos

Consultar Resultado (Fallback)

Erros

​Visão Geral

​Endpoint

​Request

​Headers

​Body

​Response

​Exemplos

​Consultar Resultado (Fallback)

​Erros

Visão Geral

Endpoint

Request

Headers

Body

Response

Exemplos

Consultar Resultado (Fallback)

Erros