Autenticação

A API Lucent KYC oferece dois métodos de autenticação dependendo do caso de uso:

🔐 Métodos de Autenticação

Método	Uso	Header	Validade	Scopes
JWT Bearer Token	Interface Web (usuários)	Authorization: Bearer {token}	1 hora (padrão)	Baseado em roles de usuário
API Key	Integração Externa (sistemas)	x-api-key: {key}	Configurável	read, write, admin

1️⃣ Autenticação JWT (Web UI)

Fluxo de Autenticação

Como Obter o JWT Token

Via Frontend (React):

import { supabase } from './supabaseClient';

// Login
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'usuario@exemplo.com',
  password: 'senha_secreta'
});

if (data.session) {
  const token = data.session.access_token;
  // Use este token nas requisições
}

Via API Direta (cURL):

curl -X POST 'https://SEU_PROJETO.supabase.co/auth/v1/token?grant_type=password' \
  -H 'apikey: SUA_SUPABASE_ANON_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "usuario@exemplo.com",
    "password": "senha_secreta"
  }'

Usando JWT nas Requisições

curl -X POST https://api.lucent-kyc.com/api/kyc/cpf \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"cpf": "12345678901", "datasets": "basic"}'

JavaScript/TypeScript:

const response = await fetch('https://api.lucent-kyc.com/api/kyc/cpf', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cpf: '12345678901',
    datasets: 'basic'
  })
});

const data = await response.json();

Renovação de Token

Expiração do Token

Tokens JWT expiram após 1 hora (padrão). Implemente renovação automática:

// Verificar expiração e renovar
supabase.auth.onAuthStateChange((event, session) => {
  if (event === 'TOKEN_REFRESHED') {
    const newToken = session?.access_token;
    // Atualizar token nas requisições
  }
});

// Renovar manualmente
const { data, error } = await supabase.auth.refreshSession();
const newToken = data.session?.access_token;

2️⃣ Autenticação por API Key (Integração Externa)

Quando Usar API Keys

API Keys são ideais para:

• 🤖 Integrações de sistemas (backend-to-backend)
• 🔄 Automações e workflows
• 📊 Ferramentas de terceiros
• 🚀 Aplicações sem interface web

Criando uma API Key

Permissão Necessária

Apenas tenant_admin pode criar API keys via web UI ou endpoint administrativo.

Via Web UI:

1. Acesse Configurações > API Keys
2. Clique em Nova API Key
3. Configure:
   • Nome: Identificação da chave
   • Descrição: Propósito da integração
   • Scope: read, write, ou admin
   • Expiração: Data opcional de expiração
4. Copie a chave completa (mostrada apenas uma vez!)

Via API (endpoint administrativo):

curl -X POST https://api.lucent-kyc.com/api/admin/api-keys \
  -H "Authorization: Bearer SEU_JWT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sistema Integração ERP",
    "description": "Consultas automáticas de clientes",
    "scope": "write",
    "expiresAt": "2026-12-31"
  }'

Resposta:

{
  "id": "uuid-da-chave",
  "key": "lk_live_abc123def456...",  // COPIE AGORA!
  "name": "Sistema Integração ERP",
  "scope": "write",
  "created_at": "2025-01-09T10:00:00Z"
}

Segurança da API Key

• A chave completa é mostrada apenas uma vez durante a criação
• Armazene em local seguro (variável de ambiente, secrets manager)
• Nunca commit a chave no controle de versão
• Rotacione periodicamente (a cada 90-180 dias)

Scopes de API Key

Scope	Permissões	Uso Recomendado
read	GET em todos os endpoints	Dashboards, relatórios, monitoramento
write	GET, POST (consultas e criação)	Integrações completas, automações
admin	GET, POST, PATCH, DELETE	Gestão completa, apenas sistemas confiáveis

Usando API Keys nas Requisições

REST API v1 (prefixo /v1/):

curl -X POST https://api.lucent-kyc.com/api/v1/kyc/cpf \
  -H "x-api-key: lk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678901",
    "datasets": ["basic", "processes"]
  }'

JavaScript/TypeScript:

const response = await fetch('https://api.lucent-kyc.com/api/v1/kyc/cpf', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.LUCENT_API_KEY, // Variável de ambiente
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cpf: '12345678901',
    datasets: ['basic', 'processes']
  })
});

const data = await response.json();

Python:

import os
import requests

API_KEY = os.getenv('LUCENT_API_KEY')

response = requests.post(
    'https://api.lucent-kyc.com/api/v1/kyc/cpf',
    headers={
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
    },
    json={
        'cpf': '12345678901',
        'datasets': ['basic', 'processes']
    }
)

data = response.json()

🔒 Segurança e Melhores Práticas

Proteção de Credenciais

✅ Faça:

• Armazene tokens/keys em variáveis de ambiente
• Use secrets managers (AWS Secrets Manager, Azure Key Vault)
• Rotacione API keys periodicamente
• Implemente HTTPS em produção (obrigatório)
• Use scopes mínimos necessários (princípio do menor privilégio)

❌ Não Faça:

• Commit tokens/keys no Git
• Expor keys no frontend (client-side)
• Compartilhar keys entre múltiplos sistemas
• Usar keys de produção em desenvolvimento

Exemplo de Configuração Segura

.env (não commitar!):

# Desenvolvimento
LUCENT_API_BASE_URL=http://localhost:3000/api
LUCENT_API_KEY=lk_test_dev123...

# Produção (configurar no servidor)
LUCENT_API_BASE_URL=https://api.lucent-kyc.com/api
LUCENT_API_KEY=lk_live_prod456...

Código:

const API_KEY = process.env.LUCENT_API_KEY;
const BASE_URL = process.env.LUCENT_API_BASE_URL;

if (!API_KEY) {
  throw new Error('LUCENT_API_KEY não configurada');
}

// Usar nas requisições

🚨 Tratamento de Erros de Autenticação

Códigos de Erro Comuns

Código	Erro	Causa	Solução
401	Unauthorized	Token/key inválido ou ausente	Verificar header de autenticação
401	Token expired	JWT expirado (>1 hora)	Renovar token com refreshSession()
403	Forbidden	Usuário sem tenant	Associar usuário a tenant válido
403	Insufficient permissions	Scope insuficiente	Usar API key com scope adequado
429	Rate limit exceeded	Muitas requisições	Implementar retry com backoff

Exemplo de Tratamento

async function makeAuthenticatedRequest(url: string, token: string) {
  try {
    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${token}` }
    });

    if (response.status === 401) {
      // Token expirado, tentar renovar
      const { data } = await supabase.auth.refreshSession();
      if (data.session) {
        // Retry com novo token
        return makeAuthenticatedRequest(url, data.session.access_token);
      } else {
        // Redirect para login
        window.location.href = '/login';
      }
    }

    if (response.status === 403) {
      throw new Error('Permissões insuficientes para esta operação');
    }

    if (response.status === 429) {
      // Rate limit, aguardar e retry
      await sleep(5000);
      return makeAuthenticatedRequest(url, token);
    }

    return response.json();
  } catch (error) {
    console.error('Erro de autenticação:', error);
    throw error;
  }
}

📊 Monitoramento de API Keys

Monitore o uso das suas API keys:

# Listar todas as keys do tenant
curl -X GET https://api.lucent-kyc.com/api/api-keys \
  -H "Authorization: Bearer SEU_JWT_TOKEN"

# Estatísticas de uso de uma key específica
curl -X GET https://api.lucent-kyc.com/api/api-keys/{key_id}/stats?period=30d \
  -H "Authorization: Bearer SEU_JWT_TOKEN"

→ Documentação completa de API Keys

🔗 Próximos Passos

• Início Rápido - Faça sua primeira consulta
• Guia de Autenticação Completo - Setup detalhado com Postman
• REST API v1 - Endpoints para integração externa
• Tratamento de Erros - Códigos e troubleshooting