Autenticación
Última actualización:
Lo que aprenderás
- Los dos transportes de credencial y cómo se elige.
- Rotación de refresh con detección de reuso.
- Respuestas del login con segundo factor.
Base: api/Auth. El único mecanismo de autenticación es la sesión de un usuario.
Transportes
Sección titulada «Transportes»| Cliente | Petición | Credencial |
|---|---|---|
| Navegador | cabecera X-Auth-Transport: cookie |
cookies sf_at (Path=/) y sf_rt (Path=/api/Auth), httpOnly, SameSite=Strict; los tokens no viajan en el cuerpo |
| Nativo / servidor | sin la cabecera | accessToken y refreshToken en el cuerpo; Authorization: Bearer en cada petición |
El esquema JWT lee la cookie de acceso sólo si no hay cabecera Authorization.
- TerceroCredenciales{ email, password }
- Sistemastatussesión · two_factor_required (challengeToken) · two_factor_enrollment_required (enrollmentToken) · password_change_required
- si aplicaTerceroPaso 2login/2fa · login/2fa/enroll[/confirm] · login/change-password
Los tokens de paso son opacos, de un solo uso, válidos 5–10 min y no emiten cookies.
Endpoints
Sección titulada «Endpoints»| Método | Ruta | Uso |
|---|---|---|
POST |
login, login/2fa, login/2fa/enroll, login/2fa/enroll/confirm, login/change-password |
inicio de sesión |
POST |
refresh |
rota el refresh token |
POST |
logout, logout-all |
cierra la sesión actual o todas |
GET / DELETE |
sessions, sessions/{id} |
sesiones activas |
POST |
forgot-password, reset-password, accept-invitation |
recuperación e invitación |
GET / POST / DELETE |
2fa, 2fa/enroll, 2fa/enroll/confirm, 2fa/recovery-codes |
segundo factor |
GET |
profile |
usuario autenticado |
POST |
change-password |
cambio con contraseña actual |
GET api/Access/me devuelve usuario, permisos y entitlements de la organización.
Refresh
Sección titulada «Refresh»- Refresh token: secreto opaco de 48 bytes, almacenado como SHA-256.
- Cada rotación revoca el anterior. Presentar un token revocado revoca toda la familia de sesión.
- El cliente debe serializar el refresh (una sola petición en curso compartida por todos los
401).
Una petición POST/PUT/PATCH/DELETE que lleva cookies de sesión sin X-Auth-Transport: cookie
se rechaza antes de autenticar. Las peticiones bearer están exentas.
Revocación
Sección titulada «Revocación»El claim tv (TokenVersion) se valida por petición con caché de 30 s. Cambio de rol, desactivación,
cambio o reset de contraseña y reset de 2FA invalidan los tokens vigentes en ≤ 30 s.