Authentication

Discord OAuth, JWT tokens, FiveM API keys, and session management for the CDE CAD platform.

CDE CAD supports multiple authentication strategies depending on the client type. Browser-based dashboards use Discord OAuth with session cookies, API consumers use JWT bearer tokens, and FiveM game servers authenticate with API keys.

Discord OAuth Flow

All user authentication begins with Discord. CDE CAD uses Discord's OAuth2 authorization code flow to verify identity and retrieve guild membership information. There is no traditional email/password registration — users must first link their Discord account before setting up CAD credentials.

Step-by-Step Flow

1. Initiate: The client redirects the user (or opens a browser window) to GET /api/auth/discord. The server redirects to Discord's authorization page.
2. Authorize: The user grants CDE CAD permission to read their Discord profile and guild list on the Discord consent screen.
3. Callback: Discord redirects back to GET /api/auth/discord/callback with an authorization code. The server exchanges this code for a Discord access token.
4. Account Resolution: The server looks up the Discord ID in the database. If the user already has a CAD account, they are logged in immediately. If not, the server returns a registration prompt.
5. Registration (new users only): New users call POST /api/auth/complete-registration with their desired CAD username, password, and security questions.
6. Token Issued: Upon successful login or registration, the server issues a JWT token and sets a session cookie. The client stores the JWT for subsequent API calls.

Flow Diagram

  Client                     CDE CAD Server                 Discord
    |                              |                            |
    |  GET /api/auth/discord       |                            |
    | ---------------------------> |                            |
    |                              |                            |
    |  302 Redirect                |                            |
    | <--------------------------- |                            |
    |                              |                            |
    |  User visits Discord OAuth consent page                   |
    | --------------------------------------------------------->|
    |                              |                            |
    |  User grants permission      |                            |
    |  302 Redirect with ?code=xxx |                            |
    | <---------------------------------------------------------|
    |                              |                            |
    |  GET /api/auth/discord/callback?code=xxx                  |
    | ---------------------------> |                            |
    |                              |  Exchange code for token   |
    |                              | -------------------------->|
    |                              |                            |
    |                              |  Discord user profile      |
    |                              | <--------------------------|
    |                              |                            |
    |  (Existing user)             |                            |
    |  Set-Cookie + JWT token      |                            |
    | <--------------------------- |                            |
    |                              |                            |
    |  (New user)                  |                            |
    |  Registration required       |                            |
    | <--------------------------- |                            |
    |                              |                            |
    |  POST /api/auth/complete-registration                     |
    | ---------------------------> |                            |
    |                              |                            |
    |  Set-Cookie + JWT token      |                            |
    | <--------------------------- |                            |

JWT Bearer Tokens

After authenticating via Discord OAuth or via the /api/auth/login endpoint, the server issues a signed JWT (JSON Web Token). This token must be included in the Authorization header for all authenticated API requests.

Token Format

JWTs are signed with a server-side secret and contain the user's ID, Discord ID, and expiration timestamp. Tokens are not encrypted — they are base64-encoded and can be decoded by anyone. Never share your token or commit it to source control.

Using the Token

Include the JWT in the Authorization header with the Bearer scheme:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example: Fetch Current User

# Login and obtain a token
curl -X POST https://cdecad.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "johndoe", "password": "s3cur3p@ss"}'

# Response:
# {
#   "token": "eyJhbGciOiJIUzI1NiIs...",
#   "user": { "id": "abc123", "username": "johndoe", ... }
# }

# Use the token for authenticated requests
curl https://cdecad.com/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

FiveM API Keys

FiveM game servers communicate with CDE CAD using dedicated API keys. These keys authenticate server-to-CAD requests such as 911 calls, panic button alerts, livemap updates, and character synchronization. API keys are not tied to individual users — they represent the FiveM server itself.

Key Format

All FiveM API keys are prefixed with fvm_ followed by a randomly generated string:

fvm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The fvm_ prefix allows the server to quickly identify the authentication method being used and route the request through the correct middleware. If a key does not have this prefix, it will be rejected.

Generating an API Key

API keys are created through the CDE CAD admin panel:

1. Navigate to your community's Admin Settings panel.
2. Open the FiveM Integration section.
3. Click Generate API Key to create a new key.
4. Copy the key immediately — it is only shown once at creation time.

Using the API Key

Include the key in the x-api-key header on every request from your FiveM server:

x-api-key: fvm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Example: Send a 911 Call from FiveM

curl -X POST https://cdecad.com/api/fivem/911 \
  -H "Content-Type: application/json" \
  -H "x-api-key: fvm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -d '{
    "callerName": "John Smith",
    "location": "Legion Square",
    "description": "Vehicle accident with injuries",
    "callerNumber": "555-0123"
  }'

API Key vs JWT

Session Authentication

For browser-based clients (the CDE CAD dashboard and admin panels), the server also maintains cookie-based sessions. When a user completes the Discord OAuth flow or logs in via the login endpoint, the server sets an HTTP-only session cookie alongside the JWT response.

How Sessions Work

Sessions are automatically sent by the browser with every request to the CDE CAD domain. You do not need to manually attach any headers — the browser handles this via cookies. This is the primary authentication method used by the CDE CAD web dashboard.

Session Lifecycle

1. Creation: A session is created when the user logs in via OAuth or the login endpoint.
2. Validation: On each request, the server validates the session cookie and hydrates the user context.
3. Expiration: Sessions expire after 24 hours of inactivity. The user must re-authenticate after expiration.
4. Logout: Calling POST /api/auth/logout destroys the session and clears the cookie.

Auth Endpoints

Complete reference for all authentication and account management endpoints.

# Open in a browser or redirect the user
curl -v https://cdecad.com/api/auth/discord
# < HTTP/1.1 302 Found
# < Location: https://discord.com/api/oauth2/authorize?client_id=...&redirect_uri=...&response_type=code&scope=identify+guilds

curl -X POST https://cdecad.com/api/auth/complete-registration \
  -H "Content-Type: application/json" \
  -d '{
    "discordId": "123456789012345678",
    "username": "johndoe",
    "password": "s3cur3p@ssw0rd",
    "securityQuestion1": "What is your pet'\''s name?",
    "securityAnswer1": "Buddy",
    "securityQuestion2": "What city were you born in?",
    "securityAnswer2": "Austin"
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "username": "johndoe",
    "discordId": "123456789012345678",
    "discordUsername": "johndoe#1234"
  }
}

curl -X POST https://cdecad.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "johndoe", "password": "s3cur3p@ss"}'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "username": "johndoe",
    "discordId": "123456789012345678",
    "discordUsername": "johndoe#1234"
  }
}

curl -X POST https://cdecad.com/api/auth/tablet-login \
  -H "Content-Type: application/json" \
  -d '{"username": "johndoe", "password": "s3cur3p@ss"}'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "username": "johndoe"
  }
}

# Get basic user info
curl https://cdecad.com/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Get user info scoped to a specific community
curl "https://cdecad.com/api/auth/me?guildId=987654321098765432" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "username": "johndoe",
  "discordId": "123456789012345678",
  "discordUsername": "johndoe#1234",
  "communities": [
    {
      "communityId": "64f1a2b3c4d5e6f7a8b9c0d2",
      "guildId": "987654321098765432",
      "role": "member",
      "permissions": ["civilian", "dispatch"]
    }
  ]
}

curl https://cdecad.com/api/auth/user \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "authenticated": true,
  "user": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "username": "johndoe"
  }
}

{
  "success": false,
  "msg": "Not authenticated"
}

curl -X POST https://cdecad.com/api/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "success": true,
  "msg": "Logged out successfully"
}

curl -X POST https://cdecad.com/api/auth/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "currentPassword": "oldP@ssw0rd",
    "newPassword": "n3wS3cur3P@ss"
  }'

{
  "success": true,
  "msg": "Password changed successfully"
}

curl "https://cdecad.com/api/auth/security-questions?username=johndoe"

{
  "securityQuestion1": "What is your pet's name?",
  "securityQuestion2": "What city were you born in?"
}

curl -X POST https://cdecad.com/api/auth/verify-security-answers \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "securityAnswer1": "Buddy",
    "securityAnswer2": "Austin"
  }'

{
  "success": true,
  "resetToken": "rst_a1b2c3d4e5f6g7h8i9j0..."
}

curl -X POST https://cdecad.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "resetToken": "rst_a1b2c3d4e5f6g7h8i9j0...",
    "newPassword": "myN3wP@ssword!"
  }'

{
  "success": true,
  "msg": "Password has been reset successfully"
}

Endpoints Summary

Permission Levels

CDE CAD uses a hierarchical role-based permission system. Every user has a role within each community they belong to. Roles determine what actions the user can perform and which API endpoints they can access.

Permission Checks in the API

When a request is made, the server checks the user's role within the relevant community. If the user does not have sufficient permissions, the server responds with 403 Forbidden:

{
  "success": false,
  "msg": "Insufficient permissions. Required role: Community Admin"
}

Some endpoints also check department-level permissions. For example, only users assigned to a law enforcement department can access LEO-specific endpoints like warrant management.

Community Scoping

CDE CAD is a multi-tenant platform where each Discord server maps to a separate community. All data (civilians, vehicles, calls, reports, departments, etc.) is isolated per community. When making API requests, you must specify which community you are operating within.

The x-community-id Header

The primary method for specifying the target community is the x-community-id request header. This header should contain the MongoDB ObjectId of the community:

x-community-id: 64f1a2b3c4d5e6f7a8b9c0d2

Example: Scoped Request

# Fetch all civilians in a specific community
curl https://cdecad.com/api/civilian \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "x-community-id: 64f1a2b3c4d5e6f7a8b9c0d2"

The communityId Parameter

Some endpoints accept communityId as a query parameter or in the request body instead of (or in addition to) the header. This is particularly common in endpoints that create or list resources:

# Create a civilian with communityId in the request body
curl -X POST https://cdecad.com/api/civilian \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "communityId": "64f1a2b3c4d5e6f7a8b9c0d2",
    "firstName": "John",
    "lastName": "Smith",
    "dateOfBirth": "1990-05-15"
  }'

How Community Scoping Works