Sign in and get an access token
POST/login
Authenticates a user and returns a JWT access token. Send the token on later calls as
Authorization: Bearer <access-token>.
Three kinds of account can sign in:
- Active Directory user: send
username,domain(NetBIOS name) andpassword. The user must be provisioned in the product (directly or through group membership). - Built-in service account: send
usernamesecureoneandpasswordwith nodomain. The account issuperadminand is disabled until its password has been changed from the default. - SAML single sign-on: when SSO is enabled, the identity provider posts its SAML response to this
endpoint. On success the server answers with a 301 redirect to
/#/login?samlAuth=<access-token>instead of a JSON body. This flow is meant for browsers.
Two-factor authentication. Depends on how the server is configured.
- No second factor configured for the user: one call returns the token.
- RADIUS enabled: always send
code(the one-time password). Without it the server returns 401 withcode2FA_Token_Required. - Built-in time-based one-time password (TOTP) enabled for the user and already enrolled: send
code. Without it the server returns 401 withcode2FA_Token_Required. - TOTP enabled but not yet enrolled: the first call (no
code) returns 200 withcode2FA_Config_Requiredand a base32key. Addkeyto an authenticator app, then call again sending the samekeyand the current six-digitcode. The server stores the key and returns the token.
The token lifetime is configurable by the administrator (default 10 hours). Read expires in the
response instead of assuming a fixed lifetime. There is no refresh endpoint; sign in again.
Both application/json and application/x-www-form-urlencoded bodies are accepted.
Required role: none (no authentication needed).
Request
Responses
- 200
- 301
- 302
- 400
- 401
- 500
- 504
Access granted, or the user must enroll a second factor. Check code in the body: when it is
2FA_Config_Required no token is issued yet.
SAML single sign-on succeeded. The Location header is /#/login?samlAuth=<access-token>; the
response has no body.
Response Headers
Relative URL carrying the access token in the samlAuth query parameter.
SAML flow mismatch. The server redirects to the single sign-on page of the server (service-provider-initiated SSO is
configured but the response was not a reply to a request) or to the identity provider entry point
(identity-provider-initiated SSO is configured but the response carries InResponseTo).
Response Headers
Bad request. Returned for a missing or empty username or domain (typed error, message Invalid request.), for a body that is not valid JSON ({error} with the parser message), for a key in the body that starts with $ (typed error, name InvalidQuery), for the built-in service account when it is disabled (the response says it is disabled and the password must be set) or the password is wrong. An unsupported content type, such as text/plain, is also Invalid request.
Authentication failed. The body is {message} for most failures (Sign In Failed when the credentials are rejected, Something went wrong, please try again., Invalid token., 2FA Configuration Required, Challenge received from RADIUS server., and for SSO User not found with <attribute>: <value> ...). Some failures return the typed error shape instead. When a second-factor code is needed the body includes code: 2FA_Token_Required; send the request again with code.
If the request also carries an invalid or expired token (an Authorization or x-access-token header, or a token field in the body or query) it fails with 401 (jwt malformed, jwt expired, invalid token) before the credentials are read. Do not send an old token when you sign in again.
Server error, for example the directory server could not be reached, the RADIUS client failed, the SAML profile lacks the configured user identifier claim, or the access token could not be issued. A non-string username or domain also returns 500; send both as strings. The body is {error} or {message}.
The RADIUS server did not answer.