Login

curl -X POST https://zou.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "mysecretpassword"
  }'

import requests

response = requests.post(
    "https://zou.example.com/api/auth/login",
    json={
        "email": "admin@example.com",
        "password": "mysecretpassword"
    }
)

data = response.json()
access_token = data["access_token"]

const response = await fetch('https://zou.example.com/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'admin@example.com',
    password: 'mysecretpassword'
  })
});

const data = await response.json();
const accessToken = data.access_token;

Log in user by creating and registering JWT auth tokens. Login is based on email and password. If no user matches the given email, it fallbacks to a desktop ID. This is useful for desktop tools that don’t know the user email. The endpoint also supports two-factor authentication via TOTP, Email OTP, FIDO, and recovery codes.

Request Body

string

required

User email addressExample: admin@example.com

string

required

User passwordExample: mysecretpassword

string

TOTP verification code for two-factor authenticationExample: 123456

string

Email OTP verification code for two-factor authenticationExample: 123456

object

FIDO authentication response for WebAuthn

string

Recovery code for two-factor authenticationExample: ABCD-EFGH-IJKL-MNOP

Response

Whether the login was successful

object

User information including id, email, first_name, last_name, role, and other profile data

object

Organisation information

string

JWT access token for API authentication

string

JWT refresh token to obtain new access tokens

boolean

Present when 2FA setup is enforced but not yet configured

Error Responses

Indicates login failure

boolean

Indicates an error occurred

boolean

User must change their default password

string

Password reset token when default_password is true

boolean

Two-factor authentication code is required but not provided

boolean

Provided OTP code is incorrect

Account locked due to too many failed login attempts

string

Error message description

Status Codes

200 - Login successful
400 - Login failed (wrong credentials, missing OTP, or validation error)
401 - User is inactive
409 - Authentication strategy not properly configured
500 - Server error (database unreachable or internal error)

Check Authentication Status

curl -X GET https://zou.example.com/api/auth/authenticated \
  -H "Authorization: Bearer <access_token>"

import requests

response = requests.get(
    "https://zou.example.com/api/auth/authenticated",
    headers={"Authorization": f"Bearer {access_token}"}
)

data = response.json()

const response = await fetch('https://zou.example.com/api/auth/authenticated', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const data = await response.json();

GET /api/auth/authenticated

Check if the user is still authenticated. Returns user information if authenticated. This endpoint can be used by third-party tools, especially browser frontends, to verify if the current user is still logged in.

Headers

string

required

Bearer token for authenticationFormat: Bearer <access_token>

Response

boolean

Always true when request succeeds

object

Current user information including profile data, role, and FIDO devices

object

Organisation information (sensitive data included for admin users)

Status Codes

200 - User authenticated
401 - Person not found or invalid token

Logout

curl -X GET https://zou.example.com/api/auth/logout \
  -H "Authorization: Bearer <access_token>"

import requests

response = requests.get(
    "https://zou.example.com/api/auth/logout",
    headers={"Authorization": f"Bearer {access_token}"}
)

const response = await fetch('https://zou.example.com/api/auth/logout', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

GET /api/auth/logout

Log user out by revoking auth tokens. Once logged out, the current user cannot access the API anymore.

Headers

string

required

Bearer token for authenticationFormat: Bearer <access_token>

Response

boolean

Always true when logout succeeds

Status Codes

200 - Logout successful
401 - Invalid or missing token
500 - Access token not found

User Registration

curl -X POST https://zou.example.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "securepassword123",
    "password_2": "securepassword123",
    "first_name": "John",
    "last_name": "Doe"
  }'

import requests

response = requests.post(
    "https://zou.example.com/api/auth/register",
    json={
        "email": "newuser@example.com",
        "password": "securepassword123",
        "password_2": "securepassword123",
        "first_name": "John",
        "last_name": "Doe"
    }
)

const response = await fetch('https://zou.example.com/api/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'newuser@example.com',
    password: 'securepassword123',
    password_2: 'securepassword123',
    first_name: 'John',
    last_name: 'Doe'
  })
});

POST /api/auth/register

Allow a user to register themselves to the service.

Request Body

string

required

User email addressExample: newuser@example.com

string

required

User password (must meet minimum length requirements)

string

required

Password confirmation (must match password)

string

required

User’s first name

string

required

User’s last name

Response

boolean

Whether registration was successful

boolean

Indicates an error occurred

string

Error message when registration fails

Status Codes

201 - Registration successful
400 - Invalid password, email, or passwords don’t match

Change Password

curl -X POST https://zou.example.com/api/auth/change-password \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "currentpassword",
    "password": "newpassword123",
    "password_2": "newpassword123"
  }'

import requests

response = requests.post(
    "https://zou.example.com/api/auth/change-password",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "old_password": "currentpassword",
        "password": "newpassword123",
        "password_2": "newpassword123"
    }
)

const response = await fetch('https://zou.example.com/api/auth/change-password', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    old_password: 'currentpassword',
    password: 'newpassword123',
    password_2: 'newpassword123'
  })
});

POST /api/auth/change-password

Allow the user to change their password. Requires current password for verification and password confirmation to ensure accuracy.

Headers

string

required

Bearer token for authenticationFormat: Bearer <access_token>

Request Body

string

required

Current password

string

required

New password

string

required

New password confirmation

Response

boolean

Whether password change was successful

boolean

Indicates an error occurred

string

Error message description

Status Codes

200 - Password changed successfully
400 - Invalid password, passwords don’t match, old password is wrong, or user is inactive

After a successful password change, a confirmation email is sent to the user’s email address.

Password Reset

Request Password Reset

curl -X POST https://zou.example.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

import requests

response = requests.post(
    "https://zou.example.com/api/auth/reset-password",
    json={"email": "user@example.com"}
)

const response = await fetch('https://zou.example.com/api/auth/reset-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com'
  })
});

POST /api/auth/reset-password

Send a password reset token by email to the user. It uses a classic scheme where a token is sent by email with a 2-hour expiration.

Request Body

string

required

User email addressExample: user@example.com

Response

string

Message indicating reset token was sent

boolean

Indicates an error occurred

string

Error message description

Status Codes

200 - Reset token sent successfully
400 - Email not listed in database or user is inactive

Reset Password with Token

curl -X PUT https://zou.example.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "token": "reset-token-from-email",
    "password": "newpassword123",
    "password2": "newpassword123"
  }'

import requests

response = requests.put(
    "https://zou.example.com/api/auth/reset-password",
    json={
        "email": "user@example.com",
        "token": "reset-token-from-email",
        "password": "newpassword123",
        "password2": "newpassword123"
    }
)

const response = await fetch('https://zou.example.com/api/auth/reset-password', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    token: 'reset-token-from-email',
    password: 'newpassword123',
    password2: 'newpassword123'
  })
});

PUT /api/auth/reset-password

Allow a user to change their password when they forget it. It uses a token sent by email to verify it is the user who requested the password reset.

Request Body

string

required

User email addressExample: user@example.com

string

required

Password reset token received via email

string

required

New password

string

required

New password confirmation

Response

boolean

Whether password reset was successful

boolean

Indicates an error occurred

string

Error message description

Status Codes

200 - Password reset successful
400 - Invalid password, passwords don’t match, wrong or expired token, or inactive user

Reset tokens expire after 2 hours and can only be used once.

​Login

​POST /api/auth/login

​Request Body

​Response

​Error Responses

​Status Codes

​Check Authentication Status

​GET /api/auth/authenticated

​Headers

​Response

​Status Codes

​Logout

​GET /api/auth/logout

​Headers

​Response

​Status Codes

​User Registration

​POST /api/auth/register

​Request Body

​Response

​Status Codes

​Change Password

​POST /api/auth/change-password

​Headers

​Request Body

​Response

​Status Codes

​Password Reset

​Request Password Reset

​POST /api/auth/reset-password

​Request Body

​Response

​Status Codes

​Reset Password with Token

​PUT /api/auth/reset-password

​Request Body

​Response

​Status Codes

POST /api/auth/login

Request Body

Response

Error Responses

Status Codes

Check Authentication Status

GET /api/auth/authenticated

Headers

Response

Status Codes

Logout

GET /api/auth/logout

Headers

Response

Status Codes

User Registration

POST /api/auth/register

Request Body

Response

Status Codes

Change Password

POST /api/auth/change-password

Headers

Request Body

Response

Status Codes

Password Reset

Request Password Reset

POST /api/auth/reset-password

Request Body

Response

Status Codes

Reset Password with Token

PUT /api/auth/reset-password

Request Body

Response

Status Codes