Pular para o conteúdo principal

Feature: Autenticação Dupla (API Key + JWT)

Introdução ao documento​

Documenta o mecanismo de autenticação dupla da API: API Key para sistemas externos e JWT para participantes.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-04
  • Responsável: Time Dhedalos

Referencial teórico​

Visão geral​

A API utiliza dois mecanismos de autenticação simultâneos:

  1. API Key — valida o sistema consumidor (app mobile) via header Authorization
  2. JWT — valida a identidade do participante para operações sensíveis (submissão de atividade)

Atores​

  • App Mobile — porta a API Key como credencial de sistema
  • Participante — recebe JWT para submissão autenticada
  • Administrador — gera API Keys via Artisan ou painel

Pré-condições​

  1. API Key gerada e registrada na tabela api_keys — Evidência: app/Console/Commands/GenerateApiKey.php:26
  2. JWT_SECRET configurado no ambiente — Evidência: app/Http/Middleware/JwtAuthenticate.php:24

Fluxo principal​

Fluxo API Key​

  1. Cliente envia request com header Authorization: <api-key>
  2. ApiKeyMiddleware::handle() extrai API Key do header
    • Evidência: app/Http/Middleware/ApiKeyMiddleware.php:17
  3. Consulta tabela api_keys por match exato
    • Evidência: app/Http/Middleware/ApiKeyMiddleware.php:28
  4. Se encontrada, request prossegue; se não, retorna HTTP 401

Fluxo JWT​

  1. App mobile obtém JWT via GET /api/submissions/token (protegido por API Key)
    • Evidência: routes/api.php:15, app/Http/Controllers/Api/SubmissionController.php:755
  2. JWT é gerado com HS256 e JWT_SECRET, validade de 1 hora
    • Evidência: app/Http/Controllers/Api/SubmissionController.php:755
  3. App mobile envia POST /api/submissions com header Authorization: Bearer <jwt>
    • Evidência: routes/api.php:34
  4. JwtAuthenticate::handle() decodifica JWT com HS256 + JWT_SECRET
    • Evidência: app/Http/Middleware/JwtAuthenticate.php:24
  5. Se válido, request prossegue; se inválido/expirado, retorna HTTP 401

Fluxos alternativos​

  • API Key ausente: Middleware retorna HTTP 401 com mensagem de erro.
  • JWT expirado: Middleware retorna HTTP 401. Cliente deve obter novo token.
  • JWT malformado: Middleware retorna HTTP 401.

Regras de negócio​

  1. API Key é obrigatória para todas as rotas API (exceto healthcheck).
    • Evidência: routes/api.php:14 (group middleware api.key)
  2. JWT é obrigatório apenas para POST /api/submissions (criação pelo participante).
    • Evidência: routes/api.php:33 (group middleware jwt.auth)
  3. Validade do JWT: 1 hora (3600 segundos).
    • Evidência: app/Http/Controllers/Api/SubmissionController.php:755
  4. Algoritmo: HS256 (HMAC SHA-256).
    • Evidência: app/Http/Middleware/JwtAuthenticate.php:24
  5. API Key: String de 64 caracteres aleatórios, gerada via Str::random(64).
    • Evidência: app/Console/Commands/GenerateApiKey.php:26

Estados possíveis​

  • Não aplicável (auth é stateless)

Endpoints envolvidos​

  • GET /api/submissions/token — obter JWT (openapi.yaml)
  • Todas as rotas em routes/api.php:14-34 — protegidas por API Key
  • POST /api/submissions — protegida por JWT (openapi.yaml)

Dados impactados​

  • api_keys — registro de chaves de API (model.md)

Pendências​

  • ⚠️ PENDÊNCIA: JWT_SECRET não consta no .env.example. Deve ser adicionado.
  • ⚠️ PENDÊNCIA: Avaliar implementação de refresh token ou extensão automática de validade do JWT.
  • ⚠️ PENDÊNCIA: Documentar procedimento de rotação de API Keys em produção.