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 →
/docsmuestra el botón Authorize, donde se pega sólo el token (Swagger agregaBearer). auto_error=Falseevita el403 "Not authenticated"por defecto: si faltan credenciales o el esquema no esBearer, se lanza el mismo401 "No autenticado"de antes.- El contrato de request no cambia: sigue siendo
Authorization: Bearer <token>.
Alternativas descartadas¶
HTTPBearer(auto_error=True)— responde403en vez de401, cambia el contrato y rompería la renovación de sesión del frontend, que reacciona al401.- Seguir con
Header()crudo — mantiene/docssin botón Authorize y el error humano al pegar el token. OAuth2PasswordBearer— implica un flujopassword/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
authorizationpor 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.