Skip to main content

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​

GET/setup

Tells you whether the site still needs its first admin account. No sign-in needed.

Response fields​

setup_requiredbooleanoptional
true while no account exists.

Responses​

200
The setup state.

Create the first admin​

POST/setup

Creates 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​

emailstringrequired
The admin's email address.
passwordstringrequired
The admin's password. At least 12 characters.

Responses​

200
The account was created. The response sets the session cookie.
403
A form post that didn't come from the site itself.
409
Setup is already done. Sign in instead.
422
The email or password is missing, the email is not valid, or the password is shorter than 12 characters.

Sign in​

POST/login

Signs 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​

emailstringrequired
Your email. Not case-sensitive.
passwordstringrequired
Your password.

Response fields​

statusstringoptional
ok.
userobjectoptional
Your account: id, email and role.

Responses​

200
You are signed in.
401
The email or password is wrong or missing, or the account is deactivated.
403
A form post that didn't come from the site itself.
429
Too many failed sign-ins. Wait for the number of seconds in Retry-After.

Sign out​

POST/logout

Ends your session on the site node and clears the cookie. The old cookie no longer works, even if it was copied.

Responses​

200
You are signed out.

Get the current user​

GET/me

Returns the account you are signed in as.

Response fields​

idintegeroptional
The user ID.
emailstringoptional
The email address.
rolestringoptional
admin or operator.

Responses​

200
Your account.
401
You are not signed in.

Change your password​

POST/me/password

Changes your own password. The session you use stays signed in. All your other sessions end.

Body​

current_passwordstringrequired
Your current password.
new_passwordstringrequired
The new password. At least 12 characters.

Responses​

200
The password was changed.
401
You are not signed in.
403
The current password is wrong.
422
The new password is too short.
429
Too many wrong current passwords: 5 within 15 minutes. Try again later.
POST/forgot-password

Emails 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​

emailstringrequired
The account's email address.

Responses​

200
The request was taken. detail is the message to show.
422
The email address is not valid.
429
Too many requests from this address. Try again later.
POST/reset-password

Sets 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​

tokenstringrequired
The code from the reset link.
new_passwordstringrequired
The new password. At least 12 characters.

Responses​

200
The password was set. Sign in with it.
400
The link is invalid, expired or already used. Request a new one.
422
The new password is too short. The link stays valid.
429
Too many attempts. Try again later.

List users​

GET/users

Lists every account on the site. Requires the admin role.

Response fields​

An array of users, each with id, email, role and created_at.

Responses​

200
The users.
401
You are not signed in.
403
You are not an admin.

Add a user​

POST/users

Creates an account. Requires the admin role. This is the only way to add users after setup.

Body​

emailstringrequired
The new user's email address. Must be unique.
passwordstringrequired
The new user's password. At least 12 characters.
rolestringoptional
operator (the default) or admin.

Responses​

200
The user was created. Returns id, email and role.
403
You are not an admin.
409
An account with this email already exists.
422
The email is not valid, the password is shorter than 12 characters, or the role is not admin or operator.

Change a user​

PATCH/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_idintegerrequired
The user.

Body​

rolestringoptional
admin or operator.
passwordstringoptional
A new password. At least 12 characters.
is_activebooleanoptional
false deactivates the user. A deactivated user can't sign in.

Response fields​

The user: id, email, role and is_active.

Responses​

200
The user was changed.
403
You are not an admin.
404
No user with this ID.
409
The user is the last active admin. Make another user an admin first.
422
The role is not valid, or the password is too short.

Deactivate a user​

DELETE/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_idintegerrequired
The user.

Responses​

200
The user was deactivated.
403
You are not an admin.
404
No user with this ID.
409
The user is the last active admin. Make another user an admin first.

Sign a user out everywhere​

POST/users/{user_id}/sessions/revoke

Ends 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_idintegerrequired
The user.

Response fields​

revokedintegeroptional
How many sessions were ended.

Responses​

200
The sessions were ended.
403
You are not an admin.
404
No user with this ID.
Was this page helpful?