Sign-in and users
These endpoints handle the first-time setup, sign-in, sessions and user accounts. See Sign-in, users and roles for how roles work.
POST /setup and POST /login take JSON. They also accept an HTML form post, but only from a page on the same site; a form post from another origin gets 403. The examples here use JSON.
Sessions
Signing in sets a session cookie. The cookie holds only a random token; the session itself is stored on the site node. The cookie is marked Secure, so it is only sent over HTTPS.
A session ends:
- After 30 minutes without a request, or 12 hours after sign-in, whichever comes first. Your administrator can change both limits.
- When you sign out. A copy of the old cookie is refused from then on.
- When an admin deactivates the user, changes their role, resets their password or signs them out.
- When you change your own password. Your other sessions end; the one you used stays signed in.
Passwords for new accounts and password changes need at least 12 characters.
Check whether setup is needed
Create the first admin
/setupCreates the first account with the admin role and signs you in. Works only on a new site, while no account exists. After that, admins add users.
Body
emailstringrequiredpasswordstringrequiredResponses
session cookie.Sign in
/loginSigns you in and sets the session cookie. Send the cookie with later requests. A deactivated account can't sign in.
Repeated failed sign-ins are throttled per client address, and per client address and account. When a limit is reached the API answers 429 with a Retry-After header giving the seconds to wait. An account that collects failures from other addresses is slowed down, never locked, so the owner can still sign in with the right password.
Body
emailstringrequiredpasswordstringrequiredResponse fields
statusstringoptionalok.userobjectoptionalid, email and role.Responses
Retry-After.Sign out
/logoutEnds your session on the site node and clears the cookie. The old cookie no longer works, even if it was copied.
Responses
Get the current user
Change your password
/me/passwordChanges your own password. The session you use stays signed in. All your other sessions end.
Body
current_passwordstringrequirednew_passwordstringrequiredResponses
Request a password reset link
/forgot-passwordEmails a single-use password reset link to the address, if it has an account and the site can send email. See Forgot your password. No sign-in needed.
The answer is the same, and takes the same time, whether or not the address has an account. The link is valid for 30 minutes, unless your administrator changed it, and a newer link cancels older ones.
Body
emailstringrequiredResponses
detail is the message to show.Set a new password with a reset link
/reset-passwordSets a new password with the code from a reset link. The code is the part of the link after #token=. No sign-in needed. The account is signed out of every session, and so is the browser that sends the request.
Body
tokenstringrequirednew_passwordstringrequiredResponses
List users
Add a user
/usersCreates an account. Requires the admin role. This is the only way to add users after setup.
Body
emailstringrequiredpasswordstringrequiredrolestringoptionaloperator (the default) or admin.Responses
id, email and role.admin or operator.Change a user
/users/{user_id}Changes a user's role, resets their password or deactivates them. Requires the admin role. Send only the fields you want to change. Each of these changes signs the user out of every session.
Path parameters
user_idintegerrequiredBody
rolestringoptionaladmin or operator.passwordstringoptionalis_activebooleanoptionalfalse deactivates the user. A deactivated user can't sign in.Response fields
The user: id, email, role and is_active.
Responses
Deactivate a user
/users/{user_id}Deactivates a user and ends all their sessions. The account is kept so the audit log and alert history still show who did what. Requires the admin role.
Path parameters
user_idintegerrequiredResponses
Sign a user out everywhere
/users/{user_id}/sessions/revokeEnds every session of a user, for example after a lost laptop. The account stays active and the user can sign in again. Requires the admin role.
Path parameters
user_idintegerrequiredResponse fields
revokedintegeroptional