Authentication
Related guides: Local sign-in and 2FA, Password grant, Single Sign-On and Session and logout.
Errors of the authentication routes are returned in JSON, with error and error_description.
POST /oauth/token
Issues the access token through OAuth 2.0 password grant, with native authentication only. Does not apply 2FA and does not accept LDAP.
Access: public.
| Header | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded, exactly |
| Field (form) | Type | Required | Description |
|---|---|---|---|
grant_type | string | Yes | Always password. |
username | string | Yes | Operator. |
password | string | Yes | Operator password. |
200 response
| Field | Description |
|---|---|
access_token | Access token for the following calls. |
scope | Operator permissions (JSON serialized as text). |
operator | Authenticated operator. |
rest_name | API registration name. |
token_type | Bearer. |
Responses
| HTTP | Meaning |
|---|---|
200 | Token issued. |
400 | Missing parameters (username, password), grant_type other than password or empty body. |
401 | Credentials not accepted or operator locked after exceeding the failure limit of the password policies. |
415 | Content-Type other than application/x-www-form-urlencoded. |
500 | Internal error. |
The token is valid for 60 minutes by default, or for the time set in session_duration in the API config.json (maximum 720 minutes).
POST /oauth/token HTTP/1.1
Host: api.example.com:33070
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=<operator>&password=<password>POST /oauth/v2/token
First step of the sign-in, with 2FA and LDAP. Receives the same form as POST /oauth/token. For LDAP, send username in the <provider>/<operator> format, with the name of the LDAP provider registered in ssoProviders.
Access: public.
| Situation | 200 response |
|---|---|
| 2FA disabled | The token, in the same format as POST /oauth/token. |
| 2FA enabled, TOTP registered | URL: challenge path (/oauth/v2/token/mfa/{challengeID}). |
| 2FA enabled, first access | URL, secret (TOTP secret in Base32) and qrcode (200 × 200 PNG in standard Base64). The secret is already stored. |
Error responses are the same as POST /oauth/token.
POST /oauth/v2/token/mfa/{challengeID}
Second step of the sign-in with 2FA. Send the 6-digit code generated by the authenticator app.
Access: public.
| Header | Value |
|---|---|
Content-Type | application/json, exactly |
| Field (JSON) | Type | Required | Description |
|---|---|---|---|
Code | string | Yes | TOTP code. |
Operator | string | No | Ignored: the API uses the challenge operator. |
Responses
| HTTP | Meaning |
|---|---|
200 | Valid code. The body brings the token, in the same format as POST /oauth/token. |
400 | Empty body, invalid JSON or Content-Type other than application/json. |
401 | Invalid code (Invalid code), nonexistent challenge (You need to authenticate first at /oauth/token) or operator locked on the fourth wrong code. |
500 | Internal error. |
POST /oauth/v2/token/mfa/<challengeID> HTTP/1.1
Host: api.example.com:33070
Content-Type: application/json
{"Code": "123456"}Single Sign-On
Routes available when there are SSO providers in the API registration. They are public and used by the browser.
| Method and route | Called by | Description |
|---|---|---|
GET /auth/api/v1/sso/login?provider=<name> | Browser | Starts the sign-in. Responds 307 to the provider (saml2 and oauth2 only), or 400 in text with an invalid provider. |
POST /auth/api/v1/sso/saml2/acs | SAML 2.0 provider | Receives SAMLResponse and RelayState. |
GET /auth/api/v1/sso/oauth2 | OAuth 2.0 provider | Receives code and state. |
POST /auth/api/v1/sso/saml2/slo | SAML 2.0 provider | Completes the federated logout and redirects (303) to the final destination. |
The sign-in returns redirect (303) to sso_login_redirect with token, token_type (Bearer) and scope (permissions as Base64-encoded JSON) in the query string. On failure, with the error parameter.
DELETE /disconnect/api/v3/logout
Ends the session and invalidates the token.
Access: Bearer.
| Header | Value |
|---|---|
Authorization | Bearer <access_token> |
Accept | application/json |
200 response
| Field | Type | Description |
|---|---|---|
data | string | Operation result (Logout successful). |
redirect | string | Logout address at the identity provider. Present only with sso_logout_end_session enabled and an SSO session. |
Responses
| HTTP | Meaning |
|---|---|
200 | Session ended. |
401 | Missing or invalid token. |
500 | Internal error. |