Begin MFA enrolment (TOTP)
POST/auth/mfa/setup
Generates a TOTP secret and returns a QR-code data URL plus the otpauth:// URI for authenticator apps. The user must call /mfa/verify with a live token to finalise enrolment. Requires the self:mfa:manage permission.
Request
Responses
- 200
- 201
- 400
- 401
- 403
- 429
- 500
MFA enrolment payload with QR code and OTP auth URI.
Resource created. Body follows the shared { data, meta } envelope; data is the newly-created resource.
The request payload failed validation. error.details lists the offending fields with human-readable messages and the class-validator constraint that fired. Fix the payload and retry — this is not a transient failure.
Missing or invalid access token.
The authenticated caller does not carry the required permission or is scoped out of this resource by the object-authorization service (e.g. an agent trying to view another agent's referrals). Grant the missing permission via a role change or scope the query to resources the caller owns.
Rate limit exceeded. Global default is 120 requests/minute per IP; auth-flow, OTP, self-registration, WebAuthn, IRA lookup, and public-lead endpoints carry tighter per-endpoint limits. Retry after the delay indicated by the Retry-After header.
Response Headers
Seconds to wait before retrying.
Unhandled server error. The response carries a meta.requestId correlator you can hand to platform operations to trace the failure through structured logs and the hash-chained audit trail. Retry with the same Idempotency-Key header if the endpoint accepts idempotency.