Saltar a contenido

0039. Esquema de seguridad Bearer en OpenAPI (botón Authorize)

Estado: Aceptado Fecha: 2026-10-05 Autor: Duval Alcivar Módulo(s) afectado(s): app/api/deps.py, tests/unit/test_deps.py, docs/adr/

Contexto

La autenticación se resuelve con get_current_user, que leía el header con un Header() crudo (ADR 0031). Consecuencia: en /docs no aparece el botón Authorize y cada endpoint protegido muestra un campo authorization suelto, donde hay que escribir Bearer <token> a mano. Es una fuente de error constante: pegar sólo el token devuelve 401 "No autenticado" y no se distingue de un header ausente.

El contrato real de la plataforma es el estándar: Authorization: Bearer <token>. Lo que falta es declararlo como esquema de seguridad para que las herramientas (Swagger UI) lo entiendan.

Decisión

get_current_user pasa a depender de HTTPBearer(auto_error=False) y se mantiene la validación propia del token:

  • El esquema se registra en OpenAPI → /docs muestra el botón Authorize, donde se pega sólo el token (Swagger agrega Bearer).
  • auto_error=False evita el 403 "Not authenticated" por defecto: si faltan credenciales o el esquema no es Bearer, se lanza el mismo 401 "No autenticado" de antes.
  • El contrato de request no cambia: sigue siendo Authorization: Bearer <token>.

Alternativas descartadas

  • HTTPBearer(auto_error=True) — responde 403 en vez de 401, cambia el contrato y rompería la renovación de sesión del frontend, que reacciona al 401.
  • Seguir con Header() crudo — mantiene /docs sin botón Authorize y el error humano al pegar el token.
  • OAuth2PasswordBearer — implica un flujo password/token que no aplica: el login es en dos pasos propio (ADR 0030).

Consecuencias

  • Sólo cambia la documentación/OpenAPI. El header que viaja en el request es idéntico, así que frontend, otros servicios y Postman no se modifican.
  • El frontend no consume el esquema generado (pone el header con su interceptor de axios); regenerar los tipos no rompe nada.
  • Desaparece el parámetro authorization por endpoint del OpenAPI, reemplazado por el esquema global.
  • El código de error se conserva: 401 "No autenticado" / 401 "Token inválido o expirado".

Qué no cubre

  • Cambio de empresa (reemitir token para otra empresa): otra decisión.
  • RLS a nivel de base: sigue sin middleware en este servicio.