Authentication

All API endpoints (except public tracking/unsubscribe URLs, webhooks, and reports) require authentication via JWT token or API key.

Login

curl -X POST https://YOUR_SERVER/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin@company.com", "password": "yourpassword"}'

Response sets an auth_token HttpOnly cookie (7-day expiry). The JWT token is used for subsequent requests.

Register

curl -X POST https://YOUR_SERVER/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Admin User", "email": "admin@company.com", "password": "yourpassword"}'

The first registered user automatically becomes super_admin. A default workspace is created on registration.

Using the Token

Two methods:

Cookie (browser/curl)

curl https://YOUR_SERVER/api/v1/workspaces \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN"

API Key (programmatic access)

curl https://YOUR_SERVER/api/v1/workspaces \
  -H "Authorization: Bearer cm_live_YOUR_API_KEY"

API keys use the cm_live_ prefix and are hashed with bcrypt before storage. Generate them from Settings → API & MCP.

Check Current User

curl https://YOUR_SERVER/api/v1/auth/me \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN"

Workspace Scoping

Most API endpoints are scoped to a workspace. Include the workspace ID in the URL path:

# All workspace-scoped endpoints follow this pattern:
curl https://YOUR_SERVER/api/v1/workspaces/:workspace_id/campaigns \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN"

# Example: List campaigns in workspace 1
curl https://YOUR_SERVER/api/v1/workspaces/1/campaigns \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN"

Roles

Session Management

• JWT tokens expire after 7 days
• API keys do not expire (revoke manually from the dashboard)
• Workspace access is enforced via middleware on every request
• Admin endpoints require super_admin or admin role

Public Endpoints (No Auth Required)