Skip to main content

​
Authentication Modes

Mission Control supports two authentication modes:

Local Token

Single shared bearer token for self-hosted deployments

Clerk JWT

Multi-user JWT authentication via Clerk

​
Configuration

The authentication mode is configured via the AUTH_MODE environment variable: 
AUTH_MODE=local  # or "clerk"

​
User Authentication

​
Local Mode

In local mode, all requests use a single shared bearer token: 
curl -H "Authorization: Bearer YOUR_LOCAL_AUTH_TOKEN" \
  https://api.example.com/api/v1/users/me
Requirements:
  • Token must be at least 50 characters
  • Token is stored in LOCAL_AUTH_TOKEN environment variable
  • All authenticated users map to a single [email protected] account

​
Clerk Mode

In Clerk mode, each user authenticates with a Clerk-issued JWT: 
curl -H "Authorization: Bearer CLERK_SESSION_TOKEN" \
  https://api.example.com/api/v1/users/me
Token Validation:
  • JWT signature is verified using Clerk’s public keys
  • User identity is extracted from the sub claim
  • Email and name are extracted from token claims or fetched from Clerk API
  • User records are automatically created/synced on first authentication

​
Agent Authentication

Agents authenticate using a separate token system. See Agent Tokens for details.

​
Authentication Flow

1

Client obtains token

  • Local mode: Token is configured in environment variables
  • Clerk mode: User signs in via Clerk UI to obtain JWT
2

Client includes token in request

Add Authorization: Bearer <token> header to all API requests
3

Backend validates token

  • Local mode: Constant-time comparison against LOCAL_AUTH_TOKEN
  • Clerk mode: JWT signature verification with clock skew tolerance
4

User context is resolved

  • Local mode: Returns or creates the local admin user
  • Clerk mode: Creates/updates user record from token claims

​
Bootstrap Endpoint

Use the bootstrap endpoint to resolve your authenticated identity: 
curl -X POST https://api.example.com/api/v1/auth/bootstrap \
  -H "Authorization: Bearer YOUR_TOKEN"
Response: 
{
  "id": "11111111-1111-1111-1111-111111111111",
  "clerk_user_id": "user_2abcXYZ",
  "email": "[email protected]",
  "name": "Alex Chen",
  "preferred_name": "Alex",
  "pronouns": "they/them",
  "timezone": "America/Los_Angeles",
  "notes": "Primary operator for board triage.",
  "context": "Handles incident coordination and escalation.",
  "is_super_admin": false
}

​
Error Responses

​
401 Unauthorized

Returned when authentication fails: 
{
  "detail": {
    "code": "unauthorized",
    "message": "Not authenticated"
  },
  "code": "unauthorized",
  "retryable": false
}
Common causes:
  • Missing Authorization header
  • Invalid token format
  • Expired JWT (Clerk mode)
  • Token mismatch (Local mode)

​
Security Considerations

Local Mode Security: Local mode uses a single shared token. Only use this mode for:
  • Self-hosted deployments with trusted network access
  • Development and testing environments
  • Single-user or single-team deployments
For multi-user production deployments, use Clerk mode.
Token Storage: Never commit tokens to version control. Use environment variables or secure secret management systems.

​
Next Steps

Local Token Setup

Configure local token authentication

Clerk Integration

Set up Clerk JWT authentication

Agent Tokens

Authenticate agent API clients

API Reference

View authentication endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us