Pular para o conteúdo principal

Autenticação e Autorização da API

Introdução ao documento​

Este documento descreve os mecanismos de autenticação/autorização aplicados nos endpoints HTTP do activity-delivery-api.

Versionamento​

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

Referencial teórico​

1) Prefixo de endpoint​

A API é publicada com prefixo /api nas rotas Laravel.

  • Evidência: routes/api.php:10-34
  • Exemplo: /api/submissions

2) API Key (serviço)​

Callback de validação​

  • Middleware: ApiKeyMiddleware::handle
  • Evidência: app/Http/Middleware/ApiKeyMiddleware.php:15

Regra aplicada​

  1. Lê header Authorization.
  2. Se ausente, retorna 401 com mensagem Missing API Key.
  3. Busca chave na tabela api_keys (ApiKey::where('key', $apiKey)).
  4. Compara com hash_equals.
  5. Se inválida, retorna 401 com mensagem Invalid API Key.
  • Evidência: app/Http/Middleware/ApiKeyMiddleware.php:17,24,27,33

Header esperado​

Authorization: <API_KEY>

3) JWT Bearer​

Callback de validação​

  • Middleware: JwtAuthenticate::handle
  • Evidência: app/Http/Middleware/JwtAuthenticate.php:13

Regra aplicada​

  1. Lê header Authorization.
  2. Exige prefixo Bearer .
  3. Extrai token e decodifica com JWT_SECRET + algoritmo HS256.
  4. Em erro de decode/expiração, retorna 401.
  • Evidência: app/Http/Middleware/JwtAuthenticate.php:15,17,24

Header esperado​

Authorization: Bearer <JWT_TOKEN>

4) Escopo de proteção observado​

TipoComo aparece no códigoEndpoints
API KeyRoute::middleware('api.key')GET /submissions, GET /submissions/{id}, POST /submissions/{id}, DELETE /submissions/{id}, GET /submissions/token, GET/DELETE /submissions/files, GET /submissions/status-sumary, activity-template-files/*
JWTRoute::middleware('jwt.auth')POST /submissions
Sanctum (sessão)->middleware('auth:sanctum')GET /user
  • Evidência: routes/api.php:10,14-29,33-34

5) Geração de credenciais de API Key​

A chave de serviço é gerada por comando Artisan.

  • Comando: api:key:generate --description=...
  • Geração de valor: Str::random(64)
  • Persistência: tabela api_keys via ApiKey::create
  • Evidência: app/Console/Commands/GenerateApiKey.php:16,28,31

6) Observações de risco técnico​

  • Uso do mesmo header Authorization para API Key e JWT em contextos distintos exige disciplina por endpoint.
    • Evidência: app/Http/Middleware/ApiKeyMiddleware.php:17, app/Http/Middleware/JwtAuthenticate.php:15
  • Retorno de erros de JWT inclui detalhe da exceção no payload (Token inválido: ...), o que pode expor detalhes operacionais.
    • Evidência: app/Http/Middleware/JwtAuthenticate.php:27

Pendências​

  • Confirmar se o endpoint GET /user (auth:sanctum) deve permanecer documentado no contrato público da API.
  • Padronizar nomenclatura de autenticação em docs/api/openapi.yaml para reduzir ambiguidade entre apiKey e bearerAuth.