POST/api/settings/mfa/recovery-codes/acknowledgeauth required
Confirm recovery codes were saved
Records that the signed-in user saved their current recovery codes. Needs a session verified with an authenticator (aal2).
Responses
200Acknowledged
| Field | Type | Required | Description |
|---|
| acknowledged | boolean | required | |
403Session not verified with an authenticator (MFA_AAL2_REQUIRED)
404No recovery codes (MFA_RECOVERY_NO_BATCH)
GET/api/settings/mfa/recovery-codesauth required
Read recovery-code status
Whether the signed-in user holds recovery codes, how many are left and whether they confirmed saving them. Never returns the codes.
Responses
200Status
| Field | Type | Required | Description |
|---|
| hasBatch | boolean | required | |
| acknowledged | boolean | required | |
| remaining | integer | required | |
| createdAt | any | required | |
| resetPending | boolean | required | |
POST/api/settings/mfa/recovery-codesauth required
Create or regenerate recovery codes
Creates ten single-use recovery codes, replacing any existing ones. This response is the only time the codes can be read. Needs a session verified with an authenticator (aal2).
Responses
200The new codes
| Field | Type | Required | Description |
|---|
| codes | string[] | required | |
| replaced | boolean | required | |
403Session not verified with an authenticator (MFA_AAL2_REQUIRED)
409A recovery was pending; it is now finished and every session is signed out. Sign in again (MFA_RECOVERY_IN_PROGRESS); or the last authenticator was removed while the codes were being created (MFA_FACTORS_CHANGED)
POST/api/settings/mfa/unenrollauth required
Remove an authenticator
Removes one of the signed-in user's verified authenticators. Needs a session verified with an authenticator (aal2). Platform admins cannot remove their last one. Removing the last one also deletes the user's recovery codes.
Request Bodyrequired
| Field | Type | Required | Description |
|---|
| factorId | string | required | |
Responses
200Removed
| Field | Type | Required | Description |
|---|
| removed | string | required | |
| remainingFactors | integer | required | |
403Session not verified with an authenticator (MFA_AAL2_REQUIRED)
404Not one of the caller's authenticators
409Last authenticator of a platform admin (PLATFORM_ADMIN_MFA_REQUIRED), or the authenticators or recovery codes changed mid-removal (MFA_FACTORS_CHANGED, retry)
GET/api/settings/opt-out-scopeauth required
Read unsubscribe scope
Whether an unsubscribe covers every address of the contact (`contact`) or only the address it came from (`address`), for the org and, with `projectId`, one project (`override` null = follows the org).
Parameters
| Name | In | Type | Required | Description |
|---|
| projectId | query | string (uuid) | optional | Also return this project's override and effective scope. |
Responses
200Current settings
| Field | Type | Required | Description |
|---|
| org | string | required | ("contact" | "address") |
| project | any | required | |
| canManage | boolean | required | |
400projectId is not a UUID
PUT/api/settings/opt-out-scopeauth required
Change unsubscribe scope
Org default (`{ scope }`) or a project override (`{ projectId, scope }`, null follows the org). Needs `org.manage`. Applies to new unsubscribes only.
Request Bodyrequired
Responses
200Updated settings
| Field | Type | Required | Description |
|---|
| org | string | required | ("contact" | "address") |
| project | any | required | |
| canManage | boolean | required | |
400Invalid body, or a null org scope