Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cgwire/zou/llms.txt

Use this file to discover all available pages before exploring further.

​
Login

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

​
POST /api/auth/login

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

​
email
string
required
User email addressExample: admin@example.com
​
password
string
required
User passwordExample: mysecretpassword
​
totp
string
TOTP verification code for two-factor authenticationExample: 123456
​
email_otp
string
Email OTP verification code for two-factor authenticationExample: 123456
​
fido_authentication_response
object
FIDO authentication response for WebAuthn
​
recovery_code
string
Recovery code for two-factor authenticationExample: ABCD-EFGH-IJKL-MNOP

​
Response

​
login
boolean
Whether the login was successful
​
user
object
User information including id, email, first_name, last_name, role, and other profile data
​
organisation
object
Organisation information
​
access_token
string
JWT access token for API authentication
​
refresh_token
string
JWT refresh token to obtain new access tokens
​
two_factor_authentication_required
boolean
Present when 2FA setup is enforced but not yet configured

​
Error Responses

​
login
boolean
default:"false"
Indicates login failure
​
error
boolean
Indicates an error occurred
​
default_password
boolean
User must change their default password
​
token
string
Password reset token when default_password is true
​
missing_OTP
boolean
Two-factor authentication code is required but not provided
​
wrong_OTP
boolean
Provided OTP code is incorrect
​
too_many_failed_login_attemps
boolean
Account locked due to too many failed login attempts
​
message
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>"

​
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

​
Authorization
string
required
Bearer token for authenticationFormat: Bearer <access_token>

​
Response

​
authenticated
boolean
Always true when request succeeds
​
user
object
Current user information including profile data, role, and FIDO devices
​
organisation
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>"

​
GET /api/auth/logout

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

​
Headers

​
Authorization
string
required
Bearer token for authenticationFormat: Bearer <access_token>

​
Response

​
logout
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"
  }'

​
POST /api/auth/register

Allow a user to register themselves to the service.

​
Request Body

​
email
string
required
User email addressExample: newuser@example.com
​
password
string
required
User password (must meet minimum length requirements)
​
password_2
string
required
Password confirmation (must match password)
​
first_name
string
required
User’s first name
​
last_name
string
required
User’s last name

​
Response

​
registration_success
boolean
Whether registration was successful
​
error
boolean
Indicates an error occurred
​
message
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"
  }'

​
POST /api/auth/change-password

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

​
Headers

​
Authorization
string
required
Bearer token for authenticationFormat: Bearer <access_token>

​
Request Body

​
old_password
string
required
Current password
​
password
string
required
New password
​
password_2
string
required
New password confirmation

​
Response

​
success
boolean
Whether password change was successful
​
error
boolean
Indicates an error occurred
​
message
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"
  }'

​
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

​
email
string
required
User email addressExample: user@example.com

​
Response

​
success
string
Message indicating reset token was sent
​
error
boolean
Indicates an error occurred
​
message
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"
  }'

​
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

​
email
string
required
User email addressExample: user@example.com
​
token
string
required
Password reset token received via email
​
password
string
required
New password
​
password2
string
required
New password confirmation

​
Response

​
success
boolean
Whether password reset was successful
​
error
boolean
Indicates an error occurred
​
message
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us