Reference
API reference
This section is the reference for the API contract. For step-by-step examples, see the Guides and Authentication.
Conventions
| Item | Value |
|---|---|
| Base URL | https://{host}/directlink/v2 |
| Credential on protected routes | Authorization: Bearer <access_token> or __Host-dirl_session cookie (the header takes precedence) |
| Request body | application/x-www-form-urlencoded, multipart/form-data, or application/octet-stream |
| Response body | application/json; binary content for downloads; XML for SAML metadata |
Access types
| Access | Meaning |
|---|---|
| Public | Does not require a credential. |
| HTTP Basic | User and password in the Authorization: Basic header. |
| Session | Bearer token or session cookie. |
| Secure link | Signed URL issued by the API; the link parameters authorize the operation. |
| Provider | Call made by the identity provider during the SSO flow. |
Endpoint catalog
| Method | Path | Access | Description |
|---|---|---|---|
GET | /healthcheck | Public | Checks availability. |
GET, POST | /auth/login | HTTP Basic | Starts the local session; can require MFA. |
GET, POST | /auth/mfa | Secure link | Validates the second factor. |
GET, POST | /auth/mfa/register | Secure link | Confirms the TOTP authenticator registration. |
POST | /auth/token | Public (OAuth form) | Issues a token through password grant or token exchange. |
POST | /oauth2/token | Public (OAuth form) | Equivalent to /auth/token. |
GET | /auth/firstaccess | Public | Starts the first access. |
GET | /auth/forget | Public | Starts password recovery. |
POST | /auth/change | Secure link | Completes the first access or the password change. |
GET, POST | /auth/logout | Session | Ends the session. |
GET | /sso/login | Public | Starts the federated login. |
GET | /sso/logout | Session | Starts the federated logout. |
GET, POST | /sso/oauth2/cb | Provider | OAuth 2.0 and 2.1/OpenID Connect callback. |
GET, POST | /sso/oauth2/logout/cb | Provider | OAuth 2.0 logout callback. |
POST | /sso/saml2/acs | Provider | Receives the SAML 2.0 assertion. |
GET, POST | /sso/saml2/slo | Provider | Receives the SAML 2.0 logout message. |
GET | /sso/saml2/metadata | Public | SAML 2.0 metadata of the provider. |
GET | /sso/saml2/metadata/{provider} | Public | SAML 2.0 metadata of the provider. |
POST | /upload | Session | Sends a file. |
GET | /download/list | Session | Lists the available files. |
GET | /download/list/backup | Session | Lists the files in the backup area. |
GET | /download/file | Secure link and token | Downloads a listed file. |
GET | /download/file/backup | Secure link and token | Downloads a file from the backup area. |
GET | /download | Secure link | Delivers a shared file. |
GET | /download/pin | Secure link | Sends the PIN and returns the download link. |
GET | /report | Session | Queries the transfer records. |
Note
When Cloudflare Turnstile is enabled in the environment, /auth/login, /auth/firstaccess and /auth/forget require the CF-Turnstile-Response header. See Cloudflare Turnstile.
In this section
OpenAPI 3.0.3 contract of the API in Portuguese, English, and Spanish, with an interactive viewer.
API availability check endpoint.
Endpoints for login, MFA, token issuance, first access, password, and logout.
Login, logout, callback, and metadata endpoints for OAuth 2.0 and 2.1/OpenID Connect and SAML 2.0.
Endpoints for upload, listing, file download, and shared links.
Endpoint for querying transfer records.
Structure of the JSON objects returned by the API.
HTTP status codes, token issuance errors, and session and transfer events.