Autenticación y sesión
Guías relacionadas: Inicio de sesión local y MFA, Tokens OAuth, Sesión y cierre de sesión y Primer acceso y contraseña.
GET POST /auth/login
Autentica al usuario con HTTP Basic y establece la sesión mediante cookie. Puede requerir MFA.
Acceso: HTTP Basic. Para un proveedor dedicado, el usuario sigue el formato PROVEDOR\USUARIO.
| Cabecera | Obligatoria | Valor |
|---|---|---|
Authorization | Sí | Basic <credenciales-base64> |
CF-Turnstile-Response | Condicional | Token de Cloudflare Turnstile. Obligatorio cuando la validación está habilitada en el entorno. Vea Cloudflare Turnstile. |
Respuestas
| HTTP | Significado | Cuerpo |
|---|---|---|
200 | Inicio de sesión completado. La sesión se envía en Set-Cookie: __Host-dirl_session. | LoginResponse |
206 | Se requiere una etapa de MFA. | MfaChallengeResponse |
400 | Credencial ausente, o header CF-Turnstile-Response ausente o no válido. | — |
401 | Credencial no aceptada. | — |
403 | Acceso denegado o token Turnstile rechazado (no válido, caducado o ya utilizado). | — |
503 | No fue posible validar el token Turnstile con Cloudflare. | — |
POST /directlink/v2/auth/login HTTP/1.1
Host: api.ejemplo.com
Authorization: Basic <credenciales-base64>
Accept: application/jsonGET POST /auth/mfa y /auth/mfa/register
/auth/mfa valida el segundo factor (status 1 y 2 del inicio de sesión). /auth/mfa/register confirma el registro del TOTP (status 3). Vea el flujo en Completar el MFA.
Acceso: enlace seguro recibido en linkURL en la respuesta 206 del inicio de sesión. Use la URL completa.
Envíe el código en el campo p: en el formulario, con POST (recomendado), o en la query string, con GET.
| Campo | Obligatorio | Descripción |
|---|---|---|
p | Sí | /auth/mfa: PIN (correo electrónico o SMS) o código TOTP. /auth/mfa/register: código TOTP generado por la aplicación con el secreto recibido. |
Respuestas de /auth/mfa
| HTTP | Significado | Cuerpo |
|---|---|---|
200 | Segundo factor validado. La sesión se envía en Set-Cookie: __Host-dirl_session. | LoginResponse |
400 | Enlace no válido o expirado, o p ausente. | — |
403 | Código TOTP no válido, usuario bloqueado o no encontrado. | — |
Respuestas de /auth/mfa/register
| HTTP | Significado | Cuerpo |
|---|---|---|
200 | TOTP registrado. No establece sesión: inicie sesión de nuevo. | MfaRegisterResponse |
400 | Enlace no válido o expirado, o p ausente. | — |
403 | Código TOTP no válido o falla al guardar el secreto. | — |
POST <ruta-completa-del-enlace-seguro> HTTP/1.1
Host: api.ejemplo.com
Content-Type: application/x-www-form-urlencoded
p=<pin-o-codigo-totp>POST /auth/token y /oauth2/token
Emiten un token de acceso Bearer. Las dos rutas son equivalentes.
Acceso: público; la credencial va en el formulario.
Cuerpo: application/x-www-form-urlencoded, según el grant.
| Campo | Password grant | Token exchange | Descripción |
|---|---|---|---|
grant_type | Sí: password | Sí: urn:ietf:params:oauth:grant-type:token-exchange | Tipo de grant. |
username | Sí | — | Usuario. |
password | Sí | — | Contraseña. |
subject_token_type | — | Sí: urn:ietf:params:oauth:token-type:jwt | Tipo del token de origen. Solo se acepta JWT. |
subject_token | — | Sí | JWT de origen. |
provider | — | No | Proveedor que valida el JWT. Prevalece sobre la cabecera X-STCPDIRECTLINK-JWT-ISSUER. |
| Cabecera | Obligatoria | Descripción |
|---|---|---|
X-STCPDIRECTLINK-JWT-ISSUER | No | Alternativa al campo provider en el token exchange. No autentica las rutas protegidas. |
Respuestas
| HTTP | Significado | Cuerpo |
|---|---|---|
200 | Token emitido. Incluye Cache-Control: no-store. | TokenResponse |
400 | Grant o token de origen no aceptado. | OAuthError |
POST /directlink/v2/oauth2/token HTTP/1.1
Host: api.ejemplo.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=password&username=<usuario>&password=<contraseña>GET /auth/firstaccess
Inicia el primer acceso. Devuelve el enlace seguro en linkURL y envía el PIN al usuario por correo electrónico o SMS.
Acceso: público.
| Parámetro | Ubicación | Obligatorio | Descripción |
|---|---|---|---|
u | query | Sí | Usuario. |
CF-Turnstile-Response | header | Condicional | Token de Cloudflare Turnstile, obligatorio cuando la validación está habilitada. |
Respuestas
| HTTP | Significado | Cuerpo |
|---|---|---|
200 | Enlace seguro en linkURL; PIN enviado al usuario. | SecureLinkResponse |
400 | Header CF-Turnstile-Response ausente o no válido. | — |
403 | Token Turnstile rechazado (no válido, caducado o ya utilizado). | — |
503 | No fue posible validar el token Turnstile con Cloudflare. | — |
GET /auth/forget
Inicia la recuperación de contraseña. Devuelve el enlace seguro en linkURL y envía el PIN al usuario por correo electrónico o SMS. Los parámetros y las respuestas son iguales a los de /auth/firstaccess.
POST /auth/change
Completa el primer acceso o la recuperación de contraseña.
Acceso: enlace seguro (linkURL) devuelto por /auth/firstaccess o /auth/forget. El k queda en la URL y contiene los parámetros de identificación y validez; no los construya manualmente.
Acepta solo POST. Envíe p y z en el cuerpo del formulario (application/x-www-form-urlencoded), nunca en la URL:
| Campo (formulario) | Obligatorio | Descripción |
|---|---|---|
p | Sí | PIN o código requerido por el flujo. |
z | Sí | Nueva contraseña. |
Respuestas
| HTTP | Significado | Cuerpo |
|---|---|---|
200 | Contraseña cambiada. | OperationResponse |
400 | Datos o enlace no válidos. | — |
403 | El cambio de contraseña fue rechazado. | — |
405 | Método distinto de POST. | — |
GET POST /auth/logout
Finaliza la sesión local. Cuando corresponde, elimina la cookie de sesión.
Acceso: sesión (token Bearer o cookie).
Respuestas
| HTTP | Significado |
|---|---|
200 | Sesión finalizada. |
401 | Credencial no aceptada. |
POST /directlink/v2/auth/logout HTTP/1.1
Host: api.ejemplo.com
Authorization: Bearer <access_token>