MFA

7 endpoints

TOTP, backup codes, and enforcement policies for step-up auth.

mfa.read

mfa.write

Read and update MFA enforcement policy. Does not cover end-user TOTP enrollment.

Authenticate with your organization API key. Include subOrgId as a query parameter or in the request body when using an org-wide key. Organization-scoped keys automatically target their organization.

GET

/v1/mfa/policy

Get MFA enforcement policy. Requires mfa.read.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "policy": { "require_mfa": false, "allowed_methods": ["totp"] } }

PATCH

/v1/mfa/policy

Update MFA enforcement policy. Requires mfa.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
require_mfa	boolean	No	Whether MFA is required
grace_period_days	integer	No	Days before MFA enforcement applies
allowed_methods	string[]	No	Allowed methods: totp, backup, sms
enforce_for_roles	string[]	No	Roles MFA applies to: owner, admin, member
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "policy": { /* updated */ } }

GET

/v1/mfa/totp

Get TOTP enrollment status for a directory user. Requires mfa.read.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.
userId	string	Yes	Directory user ID

Response — 200

{ "enrollment": { "enrolled": true, "method": "totp", "enrolledAt": "..." } }

POST

/v1/mfa/totp

Start TOTP enrollment and return a QR code. Requires mfa.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
userId	string	Yes	Directory user ID
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "pendingId": "...", "qrDataUrl": "data:image/png;base64,..." }

PUT

/v1/mfa/totp

Confirm TOTP enrollment with a 6-digit code and receive backup codes. Requires mfa.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
userId	string	Yes	Directory user ID
pendingId	string	Yes	Pending TOTP setup ID from the start enrollment response
code	string	Yes	6-digit authenticator code (or a backup code for challenges)
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "success": true, "backupCodes": ["A1B2C3D4", "..."] }

DELETE

/v1/mfa/totp

Remove TOTP enrollment for a directory user. Requires mfa.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
userId	string	Yes	Directory user ID
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "success": true }

POST

/v1/mfa/challenge/verify

Complete an MFA login challenge with a TOTP or backup code. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
challenge_token	string	Yes	Challenge token returned when login requires MFA
code	string	Yes	6-digit authenticator code (or a backup code for challenges)
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600 } }