API: Auth
Sign in and manage tokens. All endpoints require authentication unless noted. 23 endpoints.
POST /api/auth/forgot-password
Section titled “POST /api/auth/forgot-password”Request a password reset email
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
email |
string | yes |
Responses: 200 · 400 · 401 · 404
POST /api/auth/login
Section titled “POST /api/auth/login”User login
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
email |
string | yes | |
password |
string | yes | |
deviceId |
string | no |
Responses: 200 · 400 · 401 · 404
POST /api/auth/logout
Section titled “POST /api/auth/logout”Logout (revoke refresh token)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
refreshToken |
string | no |
Responses: 204 — No content · 401 · 404
GET /api/auth/me
Section titled “GET /api/auth/me”Get current user profile
Responses: 200 · 400 · 401 · 404
POST /api/auth/mfa/challenge
Section titled “POST /api/auth/mfa/challenge”Complete an MFA-gated login with a TOTP code
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
mfaToken |
string | yes | |
code |
string | yes | |
deviceId |
string | no |
Responses: 200 · 400 · 401 · 404
POST /api/auth/mfa/disable
Section titled “POST /api/auth/mfa/disable”Disable MFA (requires a valid current code)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
code |
string | yes |
Responses: 200
POST /api/auth/mfa/enable
Section titled “POST /api/auth/mfa/enable”Enable MFA after verifying a TOTP code
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
code |
string | yes |
Responses: 200
POST /api/auth/mfa/recovery-codes
Section titled “POST /api/auth/mfa/recovery-codes”Regenerate MFA recovery codes (invalidates the previous set)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
code |
string | yes |
Responses: 200
POST /api/auth/mfa/setup
Section titled “POST /api/auth/mfa/setup”Begin TOTP enrollment (returns secret + otpauth URI)
Responses: 200
GET /api/auth/mfa/status
Section titled “GET /api/auth/mfa/status”Whether TOTP MFA is enabled for the caller
Responses: 200
POST /api/auth/refresh
Section titled “POST /api/auth/refresh”Refresh access token
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
refreshToken |
string | no |
Responses: 200 · 400 · 401 · 404
POST /api/auth/register
Section titled “POST /api/auth/register”Register a new user (requires authentication)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
email |
string | yes | |
name |
string | yes | |
password |
string | yes | |
companyId |
string | yes |
Responses: 201 · 400 · 401 · 409
POST /api/auth/reset-password
Section titled “POST /api/auth/reset-password”Reset password using a reset token
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
token |
string | yes | |
password |
string | yes |
Responses: 200 · 400 · 401 · 404
GET /api/auth/sso/{slug}/login
Section titled “GET /api/auth/sso/{slug}/login”Redirect to the organization’s identity provider
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug |
string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
client |
"android" | "ios" | "windows" |
no | |
code_challenge |
string | no | |
device_id |
string | no |
Responses: 200
GET /api/auth/sso/callback
Section titled “GET /api/auth/sso/callback”OIDC callback — completes the SSO login
Responses: 200
GET /api/auth/sso/config
Section titled “GET /api/auth/sso/config”The company’s SSO configuration (secret redacted)
Responses: 200
PUT /api/auth/sso/config
Section titled “PUT /api/auth/sso/config”Create or update the company’s OIDC SSO configuration
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
issuerUrl |
string | yes | |
clientId |
string | yes | |
clientSecret |
string | no | |
allowedDomains |
array of string | no | |
autoProvision |
boolean | no | |
isEnabled |
boolean | no |
Responses: 200
DELETE /api/auth/sso/config
Section titled “DELETE /api/auth/sso/config”Remove the company’s SSO configuration
Responses: 200
POST /api/auth/sso/exchange
Section titled “POST /api/auth/sso/exchange”Exchange a mobile SSO one-time code for tokens (PKCE)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
code |
string | yes | |
codeVerifier |
string | yes |
Responses: 200 · 400 · 401 · 404
GET /api/auth/sso/lookup
Section titled “GET /api/auth/sso/lookup”Whether SSO is available for an email (returns the org slug)
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
email |
string | yes |
Responses: 200
GET /api/auth/web-session
Section titled “GET /api/auth/web-session”Redeem a WebView session code (sets cookie, redirects to the viewer)
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
code |
string | yes |
Responses: 200
POST /api/auth/web-session-code
Section titled “POST /api/auth/web-session-code”Mint a one-time code to open an authenticated WebView session
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
dashboardId |
string | no |
Responses: 200 · 400 · 401 · 404
POST /api/auth/workspace
Section titled “POST /api/auth/workspace”Switch the authenticated session to another workspace
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
workspaceId |
string | yes | |
refreshToken |
string | no |
Responses: 200 · 400 · 401 · 404