Auth API

The Auth API handles JWT token operations and user authentication with session-based login, MFA, password management, and first-time setup.

JWT Token Endpoints

Issue Token

POST /auth/token

Request Body:

{
  "applicationId": "app_abc123",
  "permissions": ["subscribe", "publish"]
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": 1710003600000
}

Verify Token

POST /auth/verify

Request Body:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Response (valid):

{
  "valid": true,
  "claims": {
    "sub": "user123",
    "aud": "app_abc123",
    "exp": 1710003600,
    "permissions": ["subscribe", "publish"]
  }
}

Response (invalid): 401 Unauthorized

User Authentication

POST /api/auth/login

Request Body:

{
  "email": "[email protected]",
  "password": "your-password"
}

Response (no MFA):

{
  "sessionToken": "sess_abc123...",
  "user": { "id": "usr_abc", "email": "[email protected]", "name": "Admin" }
}

Response (MFA required):

{
  "mfaRequired": true,
  "mfaToken": "mfa_pending_abc123"
}

MFA Verify

POST /api/auth/mfa/verify

Request Body:

{
  "mfaToken": "mfa_pending_abc123",
  "code": "123456"
}

Logout

POST /api/auth/logout

Invalidates the current session.

Get Current User

GET /api/auth/me

Returns the currently authenticated user's profile.

Password Management

Forgot Password

POST /api/auth/forgot-password

Request Body:

{
  "email": "[email protected]"
}

Reset Password

POST /api/auth/reset-password

Request Body:

{
  "token": "reset_token_abc123",
  "password": "new-secure-password"
}

First-Time Setup

Check Setup Status

GET /api/auth/setup-status

Returns whether the platform has been initialized with a first admin account.

{
  "setupRequired": true
}

Create First Admin

POST /api/auth/setup

Request Body:

{
  "name": "Admin User",
  "email": "[email protected]",
  "password": "secure-password"
}

Warning

The setup endpoint is only available when no users exist in the system. After the first admin is created, it returns 403.