Authentication API
POST /api/v1/auth/register
Summary: Register
Register a new user.
Creates a new user account and optionally a new organization. Returns JWT access token for immediate authentication.
When open registration is disabled (the default on self-hosted deployments), only the very first user may register — this bootstraps the instance owner — and all later self-service signups are rejected.
Request Schema (UserRegisterRequest):
| Property | Type | Required | Description |
|---|---|---|---|
email | string | * | User email |
password | string | * | User password (min 8 characters) |
full_name | string | * | Full name |
org_id | any | Organization ID (creates new org if not provided) | |
org_name | any | Organization name (used when creating new org) |
Response Schema (AuthResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
access_token | string | * | |
token_type | string | ||
user | AuthResponseUser | * | |
user_id | any | ||
email | any | ||
full_name | any | ||
org_id | any | ||
role | any |
POST /api/v1/auth/login
Summary: Login
Login with email and password.
Returns JWT access token on successful authentication.
If MFA is enabled or required for the user, returns an MFA token instead. Use the /auth/mfa/verify endpoint to complete login with the MFA code.
Request Schema (UserLoginRequest):
| Property | Type | Required | Description |
|---|---|---|---|
email | string | * | User email |
password | string | * | User password |
POST /api/v1/auth/mfa/verify
Summary: Verify Mfa Login
Complete login by verifying MFA code.
After receiving an MFA token from /auth/login, call this endpoint with the TOTP code from your authenticator app (or a backup code) to complete authentication and receive the access token.
The MFA token expires after 5 minutes.
Request Schema (MFALoginRequest):
| Property | Type | Required | Description |
|---|---|---|---|
mfa_code | string | * | 6-digit TOTP code or backup code (format: XXXX-XXXX) |
mfa_token | string | * | Temporary MFA token from login response |
Response Schema (MFALoginResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
user_id | string | * | |
email | string | * | |
full_name | string | * | |
org_id | string | * | |
role | string | * | |
access_token | string | * |
GET /api/v1/auth/me
Summary: Get Current User Profile
Get current user profile.
Returns details of the authenticated user.
Response Schema (UserResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
email | string | * | |
full_name | string | * | |
org_id | string | * | |
role | string | * | |
is_active | boolean | * | |
avatar_url | any | ||
created_at | string | * | |
name | string | * | Alias for full_name to match frontend expectations |
PUT /api/v1/auth/users/{user_id}/role
Summary: Update User Role
Update user role (admin only).
Only administrators can change user roles within their organization.
Request Schema (UserUpdateRole):
| Property | Type | Required | Description |
|---|---|---|---|
role | string | * | New role: admin, member, or viewer |
Response Schema (UserResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
email | string | * | |
full_name | string | * | |
org_id | string | * | |
role | string | * | |
is_active | boolean | * | |
avatar_url | any | ||
created_at | string | * | |
name | string | * | Alias for full_name to match frontend expectations |
POST /api/v1/auth/users/{user_id}/deactivate
Summary: Deactivate User
Deactivate a user account (admin only).
Deactivated users cannot log in.
POST /api/v1/auth/users/{user_id}/activate
Summary: Activate User
Activate a user account (admin only).
Allows deactivated users to log in again.
POST /api/v1/mfa/setup
Summary: Initiate Mfa Setup
Initiate MFA setup for the current user.
Returns the TOTP secret and QR code for scanning with an authenticator app. After scanning, call /mfa/verify to complete setup.
Note: This endpoint can be called multiple times to regenerate the setup data, but any existing MFA will be overwritten after verification.
Response Schema (MFASetupResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
secret | string | * | Base32 encoded TOTP secret (for manual entry) |
provisioning_uri | string | * | URI for QR code scanning |
qr_code_base64 | string | * | Base64 encoded QR code PNG image |
POST /api/v1/mfa/verify
Summary: Verify And Enable Mfa
Verify TOTP code and enable MFA.
After calling /mfa/setup, scan the QR code with your authenticator app and enter the 6-digit code here to complete setup.
Important: Save the returned backup codes in a secure location. They can be used to recover your account if you lose access to your authenticator app.
Request Schema (MFAVerifyRequest):
| Property | Type | Required | Description |
|---|---|---|---|
totp_code | string | * | 6-digit TOTP code from authenticator app |
Response Schema (MFAVerifyResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
enabled | boolean | ||
backup_codes | array of string | * | Backup codes for account recovery. SAVE THESE SECURELY! |
message | string |
GET /api/v1/mfa/status
Summary: Get Mfa Status
Get MFA status for the current user.
Returns whether MFA is enabled, when it was verified, last used, number of backup codes remaining, and organization enforcement status.
Response Schema (MFAStatusResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
enabled | boolean | * | Whether MFA is currently enabled |
verified_at | any | When MFA was verified/enabled | |
last_used_at | any | When MFA was last used for login | |
backup_codes_remaining | integer | * | Number of backup codes remaining |
org_enforces_mfa | boolean | * | Whether organization requires MFA |
setup_pending | boolean | Whether MFA setup has been initiated but not completed |
POST /api/v1/mfa/disable
Summary: Disable Mfa
Disable MFA for the current user.
Requires the current TOTP code for security verification.
Note: This endpoint will fail if the organization requires MFA.
Request Schema (MFADisableRequest):
| Property | Type | Required | Description |
|---|---|---|---|
totp_code | string | * | Current TOTP code to verify ownership |
Response Schema (MFADisableResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
enabled | boolean | ||
message | string |
POST /api/v1/mfa/backup-codes/regenerate
Summary: Regenerate Backup Codes
Regenerate backup codes.
This invalidates all existing backup codes and generates new ones. Requires the current TOTP code for security verification.
Important: Save the new backup codes in a secure location.
Request Schema (BackupCodesRegenerateRequest):
| Property | Type | Required | Description |
|---|---|---|---|
totp_code | string | * | Current TOTP code to verify ownership |
Response Schema (BackupCodesResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
backup_codes | array of string | * | New backup codes. SAVE THESE SECURELY! |
message | string |
GET /api/v1/mfa/org/status
Summary: Get Org Mfa Status
Get MFA compliance status for the organization.
Returns statistics on how many users have MFA enabled.
Requires: Organization admin role
Response Schema (OrgMFAStatusResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
mfa_required | boolean | * | Whether MFA is required for this org |
total_users | integer | * | Total users in organization |
mfa_enabled_count | integer | * | Users with MFA enabled |
mfa_pending_count | integer | * | Users without MFA |
compliance_percentage | number | * | Percentage of users with MFA |
PUT /api/v1/mfa/org/requirement
Summary: Set Org Mfa Requirement
Set MFA requirement for the organization.
When enabled, all organization members must set up MFA. Users without MFA will be prompted to set it up after login.
Requires: Organization admin role
Warning: Enabling MFA requirement may lock out users who haven't set up MFA yet. Consider notifying users first.
Request Schema (OrgMFARequirementRequest):
| Property | Type | Required | Description |
|---|---|---|---|
required | boolean | * | Whether MFA should be required for all organization members |
Response Schema (OrgMFARequirementResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
mfa_required | boolean | * | |
message | string | * |
GET /api/v1/mfa/org/users-without-mfa
Summary: Get Users Without Mfa
Get list of users who haven't set up MFA.
Useful for tracking MFA compliance and sending reminders.
Requires: Organization admin role
Response Schema (OrgUsersWithoutMFAResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
mfa_required | boolean | * | |
users | array of UserWithoutMFA | * |
GET /api/v1/oauth/{provider}/authorize
Summary: Get Authorization Url
Get OAuth authorization URL.
- provider: OAuth provider ('google' or 'microsoft')
- redirect_uri: Custom redirect URI (defaults to /api/v1/oauth/{provider}/callback)
- org_id: Organization ID for auto-provisioning
Response Schema (OAuthAuthorizeResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
authorization_url | string | * | |
state | string | * |
GET /api/v1/oauth/{provider}/callback
Summary: Oauth Callback
OAuth callback endpoint.
This endpoint receives the authorization code from the OAuth provider and exchanges it for tokens, then authenticates the user.
POST /api/v1/oauth/{provider}/login
Summary: Oauth Login
Complete OAuth login (for frontend-initiated flow).
Use this endpoint when your frontend handles the OAuth redirect and needs to exchange the code for a JWT token.
Request Schema (OAuthCallbackRequest):
| Property | Type | Required | Description |
|---|---|---|---|
code | string | * | |
state | string | * |
Response Schema (OAuthLoginResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
access_token | string | * | |
token_type | string | ||
user | object | * | |
created | boolean | * |
GET /api/v1/oauth/{provider}/link
Summary: Get Link Url
Get OAuth authorization URL for linking account.
Use this to link an OAuth provider to an existing account.
POST /api/v1/oauth/{provider}/link
Summary: Link Oauth Account
Link OAuth account to current user.
Request Schema (OAuthCallbackRequest):
| Property | Type | Required | Description |
|---|---|---|---|
code | string | * | |
state | string | * |
Response Schema (OAuthConnectionResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
provider | string | * | |
provider_email | string | * | |
provider_name | any | * | |
provider_avatar_url | any | * | |
is_primary | boolean | * | |
created_at | string | * | |
last_used_at | any | * |
DELETE /api/v1/oauth/{provider}/unlink
Summary: Unlink Oauth Account
Unlink OAuth account from current user.
GET /api/v1/oauth/connections
Summary: Get Oauth Connections
Get all OAuth connections for current user.
Response Schema (OAuthConnectionsResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
connections | array of OAuthConnectionResponse | * |
GET /api/v1/oauth/sso/config
Summary: Get Sso Config
Get SSO configuration for current user's organization.
PUT /api/v1/oauth/sso/config
Summary: Update Sso Config
Update SSO configuration for current user's organization.
Only organization admins can update SSO configuration.
Request Schema (SSOConfigUpdateRequest):
| Property | Type | Required | Description |
|---|---|---|---|
provider | string | * | |
enabled | boolean | ||
enforce_sso | boolean | ||
auto_provision | boolean | ||
default_role | string | ||
client_id | any | ||
client_secret | any | ||
allowed_domains | any |
Response Schema (SSOConfigResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
provider | string | * | |
enabled | boolean | * | |
enforce_sso | boolean | * | |
auto_provision | boolean | * | |
default_role | string | * | |
allowed_domains | array of string | * |
DELETE /api/v1/oauth/sso/config
Summary: Disable Sso
Disable SSO for current user's organization.
POST /api/v1/portal/auth/request-link
Summary: Request Magic Link
Email a sign-in magic link. Always returns 200 (no account enumeration).
Request Schema (RequestLinkRequest):
| Property | Type | Required | Description |
|---|---|---|---|
email | string | * | |
org_slug | any | ||
name | any |
Response Schema (RequestLinkResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
sent | boolean |
POST /api/v1/portal/auth/verify
Summary: Verify Magic Link
Exchange a magic-link token for a delegated end-user session token.
Request Schema (VerifyRequest):
| Property | Type | Required | Description |
|---|---|---|---|
token | string | * | |
anonymous_external_user_id | any |
Response Schema (VerifyResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
token | string | * | |
expires_at | any | * | |
external_user_id | string | * |