Authentication and session
Related guides: Local login and MFA, OAuth tokens, Session and logout, and First access and password.
GET POST /auth/login
Authenticates the user with HTTP Basic and establishes the session through a cookie. Can require MFA.
Access: HTTP Basic. For a dedicated provider, the user follows the PROVIDER\USER format.
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Basic <base64-credentials> |
CF-Turnstile-Response | Conditional | Cloudflare Turnstile token. Required when validation is enabled in the environment. See Cloudflare Turnstile. |
Responses
| HTTP | Meaning | Body |
|---|---|---|
200 | Login completed. The session is sent in Set-Cookie: __Host-dirl_session. | LoginResponse |
206 | An MFA step is required. | MfaChallengeResponse |
400 | Missing credential, or CF-Turnstile-Response header missing or invalid. | — |
401 | Credential not accepted. | — |
403 | Access denied or Turnstile token rejected (invalid, expired or already used). | — |
503 | The Turnstile token could not be validated with Cloudflare. | — |
POST /directlink/v2/auth/login HTTP/1.1
Host: api.example.com
Authorization: Basic <base64-credentials>
Accept: application/jsonGET POST /auth/mfa and /auth/mfa/register
/auth/mfa validates the second factor (login status 1 and 2). /auth/mfa/register confirms the TOTP registration (status 3). See the flow in Complete MFA.
Access: secure link received in linkURL in the login 206 response. Use the full URL.
Send the code in the p field: in the form, with POST (recommended), or in the query string, with GET.
| Field | Required | Description |
|---|---|---|
p | Yes | /auth/mfa: PIN (email or SMS) or TOTP code. /auth/mfa/register: TOTP code generated by the app with the secret received. |
/auth/mfa responses
| HTTP | Meaning | Body |
|---|---|---|
200 | Second factor validated. The session is sent in Set-Cookie: __Host-dirl_session. | LoginResponse |
400 | Invalid or expired link, or missing p. | — |
403 | Invalid TOTP code, user locked or not found. | — |
/auth/mfa/register responses
| HTTP | Meaning | Body |
|---|---|---|
200 | TOTP registered. Does not establish a session: log in again. | MfaRegisterResponse |
400 | Invalid or expired link, or missing p. | — |
403 | Invalid TOTP code or failure to store the secret. | — |
POST <full-secure-link-path> HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded
p=<pin-or-totp-code>POST /auth/token and /oauth2/token
Issue a Bearer access token. The two paths are equivalent.
Access: public; the credential goes in the form.
Body: application/x-www-form-urlencoded, according to the grant.
| Field | Password grant | Token exchange | Description |
|---|---|---|---|
grant_type | Yes: password | Yes: urn:ietf:params:oauth:grant-type:token-exchange | Grant type. |
username | Yes | — | User. |
password | Yes | — | Password. |
subject_token_type | — | Yes: urn:ietf:params:oauth:token-type:jwt | Type of the source token. Only JWT is accepted. |
subject_token | — | Yes | Source JWT. |
provider | — | No | Provider that validates the JWT. Takes precedence over the X-STCPDIRECTLINK-JWT-ISSUER header. |
| Header | Required | Description |
|---|---|---|
X-STCPDIRECTLINK-JWT-ISSUER | No | Alternative to the provider field in token exchange. Does not authenticate protected routes. |
Responses
| HTTP | Meaning | Body |
|---|---|---|
200 | Token issued. Includes Cache-Control: no-store. | TokenResponse |
400 | Grant or source token not accepted. | OAuthError |
POST /directlink/v2/oauth2/token HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=password&username=<user>&password=<password>GET /auth/firstaccess
Starts the first access. Returns the secure link in linkURL and sends the PIN to the user by email or SMS.
Access: public.
| Parameter | In | Required | Description |
|---|---|---|---|
u | query | Yes | User. |
CF-Turnstile-Response | header | Conditional | Cloudflare Turnstile token, required when validation is enabled. |
Responses
| HTTP | Meaning | Body |
|---|---|---|
200 | Secure link in linkURL; PIN sent to the user. | SecureLinkResponse |
400 | CF-Turnstile-Response header missing or invalid. | — |
403 | Turnstile token rejected (invalid, expired or already used). | — |
503 | The Turnstile token could not be validated with Cloudflare. | — |
GET /auth/forget
Starts password recovery. Returns the secure link in linkURL and sends the PIN to the user by email or SMS. Parameters and responses are the same as for /auth/firstaccess.
POST /auth/change
Completes the first access or password recovery.
Access: secure link (linkURL) returned by /auth/firstaccess or /auth/forget. The k stays in the URL and carries the identification and validity parameters; do not build them manually.
Accepts only POST. Send p and z in the form body (application/x-www-form-urlencoded), never in the URL:
| Field (form) | Required | Description |
|---|---|---|
p | Yes | PIN or code required by the flow. |
z | Yes | New password. |
Responses
| HTTP | Meaning | Body |
|---|---|---|
200 | Password changed. | OperationResponse |
400 | Invalid data or link. | — |
403 | The password change was refused. | — |
405 | Method other than POST. | — |
GET POST /auth/logout
Ends the local session. When applicable, clears the session cookie.
Access: session (Bearer token or cookie).
Responses
| HTTP | Meaning |
|---|---|
200 | Session ended. |
401 | Credential not accepted. |
POST /directlink/v2/auth/logout HTTP/1.1
Host: api.example.com
Authorization: Bearer <access_token>