/api/organizations/{organization_id}/mfa-requirementAuthenticatedRequire (or stop requiring) MFA of an organization's members
Turns the organization's multi-factor authentication requirement on or off, or changes its grace period. While MFA is required, users without a verified MFA factor cannot join the organization (accepting an invitation or being added by a platform administrator is refused). Turning it on starts a grace period of grace_period_days days for every current member without MFA and emails them; a member who later loses their last factor gets one too. A member whose grace period ends without MFA no longer counts as a member, and the enforcement job (/api/admin/organizations/enforce-mfa-requirements) removes them from the organization. Changing the grace period applies to grace periods started afterwards; turning the requirement off ends every grace period. Only organization owners and platform administrators may call it, and a caller who is a member of the organization must have MFA to turn it on. System organizations cannot require MFA.
put_api_organizations_organization_id_mfa_requirementOrganizationsAuthentication & permissionsAuthenticated
Any authenticated user
- Accepted credentials
- Auth server session (refresh token cookie)
cookie "refresh_token_<auth_server_app_id>" - Access token (cookie)
cookie "access_token_<auth_server_app_id>" - Access token (Bearer)
Authorization: Bearer <JWT>
- Auth server session (refresh token cookie)
- Who may call
- Any authenticated user
- Notes
- Only organization owners or platform administrators may change the MFA requirement.
Path parameters
| Name | Type | Description |
|---|---|---|
| organization_id* | string | Organization id (URL-safe slug) |
Request body
Required
| Property | Type | Description |
|---|---|---|
| required* | boolean | Whether members must use multi-factor authentication |
| grace_period_days | integer | Days members without MFA get to enable it. Defaults to the current grace period, or 14 days when MFA was not required yet. Ignored when minimum: 1maximum: 90 |
Responses
| Property | Type | Description |
|---|---|---|
| success* | true | |
| message* | string | |
| data* | object | |
| requirement* | OrganizationMfaRequirement | |
| organization_id* | string | minLength: 4maxLength: 32pattern: ^[a-z][a-z0-9_-]+$ |
| required* | boolean | Whether the organization requires its members to use MFA |
| grace_period_days* | integer | null | null | Grace period of members without MFA, in days; null when MFA is not required minimum: 1maximum: 90 |
| required_since* | number | null | null | Unix epoch milliseconds MFA became required; null when it is not |
| updated_at* | number | null | null | Unix epoch milliseconds the requirement was last changed; null when MFA is not required |
| caller_has_mfa* | boolean | Whether the caller has a verified MFA factor |
| members_without_mfa* | OrganizationMemberWithoutMfa[] | null | null | Members without MFA, soonest grace period end first; empty when MFA is not required. Only listed for organization owners and platform administrators (null for other members). |
| uid* | string (uuid) | The member's user id |
| email* | string (email) | |
| role* | string | Membership role in the organization: |
| membership_created_at* | number | Unix epoch milliseconds the membership was created |
| status* | "pending" | "grace_period" | "expired" |
|
| grace_period_reason* | "requirement_enabled" | "mfa_removed" | null | null | Why the grace period started: |
| grace_period_ends_at* | number | null | null | Unix epoch milliseconds the grace period ends; null while none was started |
| notified_at* | number | null | null | When the member was emailed about the requirement; null until they were |
Example request
curl -X PUT 'https://auth.schemavaults.com/api/organizations/<organization_id>/mfa-requirement' \
-b 'refresh_token_<auth_server_app_id>=<value>' \
-H 'Content-Type: application/json' \
-d '{
"required": true,
"grace_period_days": 14
}'