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.

​
Overview

Zou supports multiple two-factor authentication (2FA) methods:
  • TOTP (Time-based One-Time Password) - Using authenticator apps like Google Authenticator, Authy
  • Email OTP - One-time passwords sent via email
  • FIDO/WebAuthn - Hardware security keys and platform authenticators
  • Recovery Codes - Backup codes for account recovery
Organizations can enforce 2FA for all users. When enforcement is enabled, users must configure at least one 2FA method before gaining full access.

​
TOTP (Time-based One-Time Password)

​
Pre-enable TOTP

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

​
PUT /api/auth/totp

Prepare TOTP for enabling. Returns provisioning URI and secret for authenticator app setup.

​
Headers

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

​
Response

​
totp_provisionning_uri
string
Provisioning URI for QR code generation (can be used with authenticator apps)Example: otpauth://totp/Zou:user@example.com?secret=ABCD1234&issuer=Zou
​
otp_secret
string
TOTP secret key (can be manually entered in authenticator app)Example: ABCD1234EFGH5678

​
Status Codes

  • 200 - TOTP pre-enabled successfully
  • 400 - TOTP already enabled
  • 401 - Invalid or missing token

​
Enable TOTP

curl -X POST https://zou.example.com/api/auth/totp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "totp": "123456"
  }'

​
POST /api/auth/totp

Enable TOTP authentication. Requires verification code from authenticator app.

​
Headers

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

​
Request Body

​
totp
string
required
TOTP verification code from authenticator appExample: 123456

​
Response

​
otp_recovery_codes
string[]
Array of recovery codes for account recoveryExample: ["ABCD-EFGH-IJKL-MNOP", "QRST-UVWX-YZ12-3456"]
​
access_token
string
New access token without 2FA setup restrictions
​
refresh_token
string
New refresh token

​
Status Codes

  • 200 - TOTP enabled successfully
  • 400 - TOTP already enabled or verification failed
  • 401 - Invalid or missing token
Store recovery codes securely and display them to the user. They are only shown once and are needed if the user loses access to their authenticator app.

​
Disable TOTP

curl -X DELETE https://zou.example.com/api/auth/totp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "totp": "123456"
  }'

​
DELETE /api/auth/totp

Disable TOTP authentication. Requires two-factor authentication verification.

​
Headers

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

​
Request Body

​
totp
string
TOTP verification code
​
email_otp
string
Email OTP verification code
​
fido_authentication_response
object
FIDO authentication response
​
recovery_code
string
Recovery code for two-factor authentication
At least one 2FA method must be provided to disable TOTP.

​
Response

​
success
boolean
Whether TOTP was disabled successfully

​
Status Codes

  • 200 - TOTP disabled successfully
  • 400 - TOTP not enabled or verification failed
  • 401 - Invalid or missing token

​
Email OTP

​
Send Email OTP

curl -X GET "https://zou.example.com/api/auth/email-otp?email=user@example.com"

​
GET /api/auth/email-otp

Send a one-time password by email to the user for authentication.

​
Query Parameters

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

​
Response

​
success
boolean
Whether OTP was sent successfully

​
Status Codes

  • 200 - OTP sent successfully
  • 400 - OTP by email not enabled
  • 404 - User not found

​
Pre-enable Email OTP

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

​
PUT /api/auth/email-otp

Prepare email OTP for enabling. An OTP code will be sent to the user’s email address.

​
Headers

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

​
Response

​
success
boolean
Whether email OTP pre-enable was successful

​
Status Codes

  • 200 - Email OTP pre-enabled, code sent
  • 400 - Email OTP already enabled
  • 401 - Invalid or missing token

​
Enable Email OTP

curl -X POST https://zou.example.com/api/auth/email-otp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email_otp": "123456"
  }'

​
POST /api/auth/email-otp

Enable email OTP authentication. Requires verification code sent to email.

​
Headers

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

​
Request Body

​
email_otp
string
required
Email OTP verification codeExample: 123456

​
Response

​
otp_recovery_codes
string[]
Array of recovery codes for account recovery
​
access_token
string
New access token without 2FA setup restrictions
​
refresh_token
string
New refresh token

​
Status Codes

  • 200 - Email OTP enabled successfully
  • 400 - Email OTP already enabled or verification failed
  • 401 - Invalid or missing token

​
Disable Email OTP

curl -X DELETE https://zou.example.com/api/auth/email-otp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email_otp": "123456"
  }'

​
DELETE /api/auth/email-otp

Disable email OTP authentication. Requires two-factor authentication verification.

​
Headers

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

​
Request Body

​
totp
string
TOTP verification code
​
email_otp
string
Email OTP verification code
​
fido_authentication_response
object
FIDO authentication response
​
recovery_code
string
Recovery code for two-factor authentication

​
Response

​
success
boolean
Whether email OTP was disabled successfully

​
Status Codes

  • 200 - Email OTP disabled successfully
  • 400 - Email OTP not enabled or verification failed
  • 401 - Invalid or missing token

​
FIDO/WebAuthn

​
Get FIDO Challenge

curl -X GET "https://zou.example.com/api/auth/fido?email=user@example.com"

​
GET /api/auth/fido

Get a challenge for FIDO device authentication. Used for WebAuthn authentication flow.

​
Query Parameters

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

​
Response

Returns WebAuthn challenge object for authentication.

​
Status Codes

  • 200 - FIDO challenge generated
  • 400 - FIDO not enabled
  • 404 - User not found

​
Pre-register FIDO Device

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

​
PUT /api/auth/fido

Prepare FIDO device for registration. Returns registration options for WebAuthn.

​
Headers

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

​
Response

Returns WebAuthn registration options object.

​
Status Codes

  • 200 - FIDO device pre-registered
  • 401 - Invalid or missing token

​
Register FIDO Device

curl -X POST https://zou.example.com/api/auth/fido \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "registration_response": {...},
    "device_name": "YubiKey 5"
  }'

​
POST /api/auth/fido

Register a FIDO device for WebAuthn authentication. Requires registration response from the device.

​
Headers

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

​
Request Body

​
registration_response
object
required
FIDO device registration response from WebAuthn API
​
device_name
string
required
Name for the FIDO deviceExample: YubiKey 5, Touch ID, Windows Hello

​
Response

​
otp_recovery_codes
string[]
Array of recovery codes for account recovery
​
access_token
string
New access token without 2FA setup restrictions
​
refresh_token
string
New refresh token

​
Status Codes

  • 200 - FIDO device registered successfully
  • 400 - Registration failed or no preregistration
  • 401 - Invalid or missing token

​
Unregister FIDO Device

curl -X DELETE https://zou.example.com/api/auth/fido \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_name": "YubiKey 5"
  }'

​
DELETE /api/auth/fido

Unregister a FIDO device from WebAuthn authentication. The user must be authenticated.

​
Headers

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

​
Request Body

​
device_name
string
required
Name of the FIDO device to unregister

​
Response

​
success
boolean
Whether device was unregistered successfully

​
Status Codes

  • 200 - FIDO device unregistered successfully
  • 400 - FIDO not enabled
  • 401 - Invalid or missing token

​
Recovery Codes

​
Generate New Recovery Codes

curl -X PUT https://zou.example.com/api/auth/recovery-codes \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "totp": "123456"
  }'

​
PUT /api/auth/recovery-codes

Generate new recovery codes for two-factor authentication. Requires two-factor authentication verification. Previous recovery codes will be invalidated.

​
Headers

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

​
Request Body

​
totp
string
TOTP verification code
​
email_otp
string
Email OTP verification code
​
fido_authentication_response
object
FIDO authentication response
​
recovery_code
string
Recovery code for two-factor authentication
At least one 2FA method must be provided to generate new recovery codes.

​
Response

​
otp_recovery_codes
string[]
Array of new recovery codesExample: ["ABCD-EFGH-IJKL-MNOP", "QRST-UVWX-YZ12-3456"]

​
Status Codes

  • 200 - New recovery codes generated
  • 400 - No 2FA enabled or verification failed
  • 401 - Invalid or missing token
All previous recovery codes will be invalidated when new codes are generated. Store the new codes securely.

​
2FA Enforcement

When 2FA enforcement is enabled (ENFORCE_2FA config), users must configure at least one 2FA method.

​
Enforcement Flow

  1. User logs in with email and password
  2. If 2FA is not configured, login succeeds but with restricted access
  3. Access token includes requires_2fa_setup claim
  4. User can only access 2FA setup endpoints
  5. After configuring 2FA, new tokens are issued without restrictions

​
Login Response with 2FA Required

{
  "login": true,
  "user": {...},
  "organisation": {...},
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "two_factor_authentication_required": true
}
The two_factor_authentication_required flag indicates that 2FA setup is required before gaining full access.

​
Completing 2FA Setup

After configuring any 2FA method (TOTP, Email OTP, or FIDO), the API returns new tokens without restrictions: 
{
  "otp_recovery_codes": ["ABCD-EFGH-IJKL-MNOP", ...],
  "access_token": "eyJ...",  // New token without restrictions
  "refresh_token": "eyJ..."  // New refresh token
}

​
Exemptions

Certain users can be exempted from 2FA enforcement through server configuration. Contact your administrator for exemption policies.

Build docs developers (and LLMs) love

Get started for freeTalk to us