Pragence

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):

PropertyTypeRequiredDescription
emailstring*User email
passwordstring*User password (min 8 characters)
full_namestring*Full name
org_idanyOrganization ID (creates new org if not provided)
org_nameanyOrganization name (used when creating new org)

Response Schema (AuthResponse - Status 201):

PropertyTypeRequiredDescription
access_tokenstring*
token_typestring
userAuthResponseUser*
user_idany
emailany
full_nameany
org_idany
roleany

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):

PropertyTypeRequiredDescription
emailstring*User email
passwordstring*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):

PropertyTypeRequiredDescription
mfa_codestring*6-digit TOTP code or backup code (format: XXXX-XXXX)
mfa_tokenstring*Temporary MFA token from login response

Response Schema (MFALoginResponse - Status 200):

PropertyTypeRequiredDescription
user_idstring*
emailstring*
full_namestring*
org_idstring*
rolestring*
access_tokenstring*

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):

PropertyTypeRequiredDescription
idstring*
emailstring*
full_namestring*
org_idstring*
rolestring*
is_activeboolean*
avatar_urlany
created_atstring*
namestring*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):

PropertyTypeRequiredDescription
rolestring*New role: admin, member, or viewer

Response Schema (UserResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
emailstring*
full_namestring*
org_idstring*
rolestring*
is_activeboolean*
avatar_urlany
created_atstring*
namestring*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):

PropertyTypeRequiredDescription
secretstring*Base32 encoded TOTP secret (for manual entry)
provisioning_uristring*URI for QR code scanning
qr_code_base64string*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):

PropertyTypeRequiredDescription
totp_codestring*6-digit TOTP code from authenticator app

Response Schema (MFAVerifyResponse - Status 200):

PropertyTypeRequiredDescription
enabledboolean
backup_codesarray of string*Backup codes for account recovery. SAVE THESE SECURELY!
messagestring

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):

PropertyTypeRequiredDescription
enabledboolean*Whether MFA is currently enabled
verified_atanyWhen MFA was verified/enabled
last_used_atanyWhen MFA was last used for login
backup_codes_remaininginteger*Number of backup codes remaining
org_enforces_mfaboolean*Whether organization requires MFA
setup_pendingbooleanWhether 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):

PropertyTypeRequiredDescription
totp_codestring*Current TOTP code to verify ownership

Response Schema (MFADisableResponse - Status 200):

PropertyTypeRequiredDescription
enabledboolean
messagestring

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):

PropertyTypeRequiredDescription
totp_codestring*Current TOTP code to verify ownership

Response Schema (BackupCodesResponse - Status 200):

PropertyTypeRequiredDescription
backup_codesarray of string*New backup codes. SAVE THESE SECURELY!
messagestring

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):

PropertyTypeRequiredDescription
org_idstring*
mfa_requiredboolean*Whether MFA is required for this org
total_usersinteger*Total users in organization
mfa_enabled_countinteger*Users with MFA enabled
mfa_pending_countinteger*Users without MFA
compliance_percentagenumber*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):

PropertyTypeRequiredDescription
requiredboolean*Whether MFA should be required for all organization members

Response Schema (OrgMFARequirementResponse - Status 200):

PropertyTypeRequiredDescription
org_idstring*
mfa_requiredboolean*
messagestring*

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):

PropertyTypeRequiredDescription
org_idstring*
mfa_requiredboolean*
usersarray 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):

PropertyTypeRequiredDescription
authorization_urlstring*
statestring*

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):

PropertyTypeRequiredDescription
codestring*
statestring*

Response Schema (OAuthLoginResponse - Status 200):

PropertyTypeRequiredDescription
access_tokenstring*
token_typestring
userobject*
createdboolean*

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):

PropertyTypeRequiredDescription
codestring*
statestring*

Response Schema (OAuthConnectionResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
providerstring*
provider_emailstring*
provider_nameany*
provider_avatar_urlany*
is_primaryboolean*
created_atstring*
last_used_atany*

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):

PropertyTypeRequiredDescription
connectionsarray 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):

PropertyTypeRequiredDescription
providerstring*
enabledboolean
enforce_ssoboolean
auto_provisionboolean
default_rolestring
client_idany
client_secretany
allowed_domainsany

Response Schema (SSOConfigResponse - Status 200):

PropertyTypeRequiredDescription
org_idstring*
providerstring*
enabledboolean*
enforce_ssoboolean*
auto_provisionboolean*
default_rolestring*
allowed_domainsarray 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):

PropertyTypeRequiredDescription
emailstring*
org_slugany
nameany

Response Schema (RequestLinkResponse - Status 200):

PropertyTypeRequiredDescription
sentboolean

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):

PropertyTypeRequiredDescription
tokenstring*
anonymous_external_user_idany

Response Schema (VerifyResponse - Status 200):

PropertyTypeRequiredDescription
tokenstring*
expires_atany*
external_user_idstring*

On this page