Settings

6 endpoints

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
FieldTypeRequiredDescription
acknowledgedbooleanrequired
401Unauthorized
403Session not verified with an authenticator (MFA_AAL2_REQUIRED)
404No recovery codes (MFA_RECOVERY_NO_BATCH)
500Internal server error
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
FieldTypeRequiredDescription
hasBatchbooleanrequired
acknowledgedbooleanrequired
remainingintegerrequired
createdAtanyrequired
resetPendingbooleanrequired
401Unauthorized
500Internal server error
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
FieldTypeRequiredDescription
codesstring[]required
replacedbooleanrequired
401Unauthorized
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)
500Internal server error
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
FieldTypeRequiredDescription
factorIdstringrequired
Responses
200Removed
FieldTypeRequiredDescription
removedstringrequired
remainingFactorsintegerrequired
400Invalid body
401Unauthorized
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)
500Internal server error
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
NameInTypeRequiredDescription
projectIdquerystring (uuid)optionalAlso return this project's override and effective scope.
Responses
200Current settings
FieldTypeRequiredDescription
orgstringrequired("contact" | "address")
projectanyrequired
canManagebooleanrequired
400projectId is not a UUID
401Unauthorized
500Internal server error
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
FieldTypeRequiredDescription
orgstringrequired("contact" | "address")
projectanyrequired
canManagebooleanrequired
400Invalid body, or a null org scope
401Unauthorized
403Missing org.manage
500Internal server error