Authentication

Login

POST /api/login

Creates a login session or retrieves information about the currently existing session (“passive login”).

Can be used in one of two ways: to login a user via username and password and create a persistent session (usually from a UI in the browser), or to retrieve information about the active user (from an existing session or an API key) via the passive flag.

Will return a 200 OK with a login response on successful login, whether active or passive. The active (username/password) login may also return a 403 Forbidden in case of a username/password mismatch, unknown user or a deactivated account.

Warning

Previous versions of this API endpoint did return a 401 Unauthorized in case of a username/password mismatch or an unknown user. That was incompatible with basic authentication since it was a wrong use of the 401 Unauthorized code and got therefore changed as part of a bug fix.

Note

You cannot use this endpoint to login from a third party page via CORS, see above. You can however use it to retrieve user information via passive login with an API key (e.g. if you need the session to authenticate on the web socket.

JSON Parameters:

  • passive – If present, performs a passive login only, returning information about the current user that’s active either through an existing session or the used API key

  • user – (active login only) Username

  • pass – (active login only) Password

  • remember – (active login only) Whether to set a “remember me” cookie on the session

Status Codes:

  • 200 OK – Successful login

  • 403 Forbidden – Username/password mismatch, unknown user or deactivated account

Logout

POST /api/logout

Ends the current login session of the current user.

Only makes sense in the context of browser based workflows.

Will return a 204 No Content.

Status Codes:

Current User

GET /api/currentuser

Retrieves information about the current user.

Will return a 200 OK with a current user object as body.

Status Codes:

Data model

Login response

The Login response is a user record extended by the following fields:

Name

Multiplicity

Type

Description

session

1

string

The session key, can be used to authenticate with the auth message on the push API.

_is_external_client

1

boolean

Whether the client that made the request got detected as external from the local network or not.

Current user

Name

Multiplicity

Type

Description

name

1

string

The id of the current user. Unset if guest.

permissions

0..n

List of permission records

The effective list of permissions assigned to the user

groups

0..n

List of permission records

The list of groups assigned to the user