Skip to main content

​
Overview

The Authentication API provides endpoints for user login, registration, 2FA management, and session handling. All authenticated endpoints require a valid JWT token set via cookies.

​
Authentication Flow

SnailyCAD uses JWT-based authentication with access and refresh tokens stored in HTTP-only cookies:
  • snaily-cad-access-token - Short-lived access token
  • snaily-cad-refresh-token - Long-lived refresh token

​
Login

curl -X POST https://your-cad.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "password": "your-password",
    "totpCode": "123456"
  }'
Authenticate a user via username and password. Returns user ID and sets authentication cookies.

​
Request Body

​
username
string
required
The user’s username (case-insensitive)
​
password
string
required
The user’s password
​
totpCode
string
Two-factor authentication code (required if 2FA is enabled)

​
Response

​
userId
string
The authenticated user’s ID
​
hasTempPassword
boolean
Indicates if the user needs to change their temporary password

​
Error Responses

  • 404 - User not found
  • 400 - Invalid credentials, whitelist pending/declined, or user banned
  • 400 - 2FA code required or invalid

​
Register

curl -X POST https://your-cad.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "password": "secure-password",
    "registrationCode": "optional-code"
  }'
Create a new user account. The first registered user automatically becomes the CAD owner.

​
Request Body

​
username
string
required
Username (alphanumeric, underscores, and periods only)
​
password
string
required
Password (minimum 8 characters)
​
registrationCode
string
Registration code if required by the CAD
​
steamId
string
Steam ID for linking Steam account
​
discordId
string
Discord ID for linking Discord account

​
Response

​
userId
string
The newly created user’s ID
​
isOwner
boolean
Whether the user is the CAD owner
​
whitelistStatus
string
User’s whitelist status: ACCEPTED, PENDING, or DECLINED

​
Get Current User

curl -X POST https://your-cad.com/api/user \
  -H "Cookie: snaily-cad-access-token=<token>" \
  -H "Content-Type: application/json"
Get the authenticated user’s information and CAD settings.

​
Query Parameters

​
includeActiveUnit
boolean
Include the user’s currently active LEO/EMS-FD unit

​
Response

​
id
string
User ID
​
username
string
Username
​
rank
string
User rank: OWNER, ADMIN, USER, etc.
​
permissions
array
Array of permission strings
​
cad
object
CAD configuration and settings
​
unit
object
Active officer or deputy (if includeActiveUnit=true)

​
Update User Settings

curl -X PATCH https://your-cad.com/api/user \
  -H "Cookie: snaily-cad-access-token=<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new_username",
    "isDarkTheme": true,
    "locale": "en"
  }'
Update the authenticated user’s settings and preferences.

​
Request Body

​
username
string
New username
​
isDarkTheme
boolean
Enable dark theme
​
locale
string
Preferred language locale (e.g., en, de, fr)
​
statusViewMode
string
Status view mode preference
​
tableActionsAlignment
string
Table actions alignment preference
​
soundSettings
object
Sound notification settings

​
Logout

curl -X POST https://your-cad.com/api/user/logout \
  -H "Cookie: snaily-cad-access-token=<token>"
Logout the authenticated user, clearing all sessions and setting active units off-duty.

​
Response

Returns true on success.

​
Change Password

curl -X POST https://your-cad.com/api/user/password \
  -H "Cookie: snaily-cad-access-token=<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "old-password",
    "newPassword": "new-password",
    "confirmPassword": "new-password"
  }'
Update the user’s password.

​
Request Body

​
currentPassword
string
required
Current password (not required for OAuth users)
​
newPassword
string
required
New password (minimum 8 characters)
​
confirmPassword
string
required
Confirmation of new password (must match)

​
Two-Factor Authentication

​
Enable 2FA

curl -X POST https://your-cad.com/api/2fa/enable \
  -H "Cookie: snaily-cad-access-token=<token>" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword": "your-password"}'
Enable two-factor authentication for the user.

​
Request Body

​
currentPassword
string
required
User’s current password for verification

​
Response

​
qrCode
string
Data URI of QR code for authenticator apps
​
totpCode
string
Secret key for manual entry

​
Verify 2FA Code

curl -X POST https://your-cad.com/api/2fa/verify \
  -H "Cookie: snaily-cad-access-token=<token>" \
  -H "Content-Type: application/json" \
  -d '{"totpCode": "123456"}'
Verify a TOTP code.

​
Request Body

​
totpCode
string
required
6-digit code from authenticator app

​
Disable 2FA

curl -X DELETE https://your-cad.com/api/2fa \
  -H "Cookie: snaily-cad-access-token=<token>" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword": "your-password"}'
Disable two-factor authentication.

​
Request Body

​
currentPassword
string
required
User’s current password for verification

​
Delete Account

curl -X DELETE https://your-cad.com/api/user \
  -H "Cookie: snaily-cad-access-token=<token>"
Permanently delete the user’s account. CAD owners cannot delete their accounts.

​
Response

Returns true on success.

​
Error Responses

  • 400 - Cannot delete owner account

Build docs developers (and LLMs) love

Get started for freeTalk to us