Autenticação

A Seguros API aceita dois mecanismos de autenticação: API key via header x-api-key (para integrações server-to-server) e JWT via cookie access_token ou header Authorization: Bearer (para operadores logados no portal). O guard padrão (JwtOrApiKeyGuard) tenta JWT primeiro e cai para API key se o JWT estiver ausente ou inválido.

Base URL de produção: https://api-seguros.simplafy.com.br.

Visão geral

Cada request protegida precisa apresentar uma das credenciais abaixo. A ordem de avaliação é fixa:

1. JWT — cookie httpOnly access_token ou header Authorization: Bearer <token>.
2. API key — header x-api-key: <chave>.

Se ambas falharem, a API responde 401 Unauthorized. Se nenhuma estiver presente, o resultado é o mesmo.

A identidade resolvida (JWT ou API key) é exposta como request.user com o formato:

{
  "id": "uuid-do-usuario",
  "username": "[email protected]",
  "role": "admin"
}

API key (header)

Use para integrações headless (n8n, scripts, webhooks externos). A chave é uma string hex de 64 caracteres gerada por randomBytes(32).

Criar uma API key

API keys são criadas por um operador autenticado via JWT no endpoint POST /api-keys. A chave fica vinculada a um usuário existente — toda request feita com ela passa a usar a identidade desse usuário.

curl -X POST https://api-seguros.simplafy.com.br/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=<jwt-do-operador>" \
  -d '{"email": "[email protected]"}'

Resposta:

{
  "id": "uuid-da-chave",
  "key": "a1b2c3...64chars",
  "user": { "id": "uuid", "email": "[email protected]" }
}

Usar a API key

Envie o header x-api-key em qualquer endpoint protegido pelo JwtOrApiKeyGuard:

curl https://api-seguros.simplafy.com.br/policy \
  -H "x-api-key: a1b2c3...64chars"

const res = await fetch('https://api-seguros.simplafy.com.br/policy', {
  headers: { 'x-api-key': process.env.SEGUROS_API_KEY! },
});

import os, requests

res = requests.get(
    "https://api-seguros.simplafy.com.br/policy",
    headers={"x-api-key": os.environ["SEGUROS_API_KEY"]},
)

JWT (login operadores)

Operadores autenticam com email/senha e recebem dois tokens em cookies httpOnly: access_token (1h) e refresh_token (7 dias). O endpoint não retorna os tokens no corpo da resposta.

Login

curl -X POST https://api-seguros.simplafy.com.br/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email": "[email protected]", "password": "senha-em-claro"}'

Resposta 200:

{
  "message": "Login successful",
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "Nome do Operador"
  }
}

Cookies definidos pelo servidor:

Em produção os cookies usam domain=.simplafy.com.br para compartilhamento entre subdomínios.

Renovar access token

Antes do access_token expirar (ou ao receber 401), chame POST /auth/refresh. O refresh_token enviado pelo cookie é usado para emitir um novo access_token:

curl -X POST https://api-seguros.simplafy.com.br/auth/refresh \
  -b cookies.txt -c cookies.txt

Erros possíveis: 401 se o refresh estiver ausente, expirado ou revogado.

Logout

Revoga o refresh_token no banco e limpa ambos os cookies:

curl -X POST https://api-seguros.simplafy.com.br/auth/logout \
  -b cookies.txt -c cookies.txt

Usar JWT como Bearer

Para clientes não-browser que preferem header em vez de cookie, o mesmo token aceito em access_token também é aceito em Authorization:

curl https://api-seguros.simplafy.com.br/policy \
  -H "Authorization: Bearer <access_token>"

Recuperação de senha

Dois endpoints públicos (não exigem autenticação):

• POST /auth/forgot-password — recebe { email } e envia link de reset via Resend. Sempre responde sucesso para evitar enumeração de emails.
• POST /auth/reset-password — recebe { token, newPassword }. O token vale 1 hora e só pode ser usado uma vez.

Permissões

A identidade resolvida carrega o campo role, que controla acesso a recursos sensíveis. Roles observados no código:

Endpoints sensíveis aplicam guards adicionais. Exemplo: AuditViewGuard restringe /audit-logs/* a roles admin e manager, retornando 403 Forbidden para os demais.

Erros

Códigos retornados pelos guards e pelo módulo auth:

Formato típico do payload de erro (NestJS default):

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Para erros de reset de senha, a message é localizada (Token inválido ou expirado, Este link já foi utilizado, Token expirado. Solicite nova recuperação).