Back to API overview
MFA
2 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. Sub-org-scoped keys automatically target their sub-organization.GET
/v1/mfa/policyGet MFA enforcement policy. Requires mfa.read.
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
| subOrgId | string | No | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
Response — 200
{ "policy": { "require_mfa": false, "allowed_methods": ["totp"] } }
PATCH
/v1/mfa/policyUpdate MFA enforcement policy. Requires mfa.write.
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
| subOrgId | string | No | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
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 | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
Response — 200
{ "policy": { /* updated */ } }