Setup MFA

Initiates Multi-Factor Authentication (MFA) setup for the authenticated user. Returns a QR code and TOTP secret that must be scanned with an authenticator app (Google Authenticator, Authy, etc.). After scanning, the user must confirm setup with a verification code via the Confirm MFA Setup endpoint.

Request

POST /mfa/setup

Authentication

Requires a valid Bearer JWT token in the Authorization header.

Authorization: Bearer <access_token>

Request Body

No request body required.

Response

Returns an MfaSetupResponse object containing the QR code and secret for TOTP configuration.

{
  "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEs...",
  "secret": "JBSWY3DPEHPK3PXP"
}

Response Fields

Field	Type	Description
qrCodeBase64	string	Base64-encoded PNG image of the QR code. Decode and display to the user for scanning with their authenticator app.
secret	string	TOTP secret key in Base32 format. Users can manually enter this into their authenticator app if they cannot scan the QR code.

Error Responses

Status Code	Error	Description
401	Unauthorized	Invalid or missing JWT token
409	Conflict	MFA is already enabled for this user

Example

Request

curl -X POST https://api.entryguard.io/api/v1/mfa/setup \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
  "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAAACXBIWXMAAAsTAAALEwEAmpwYAAAKT2lDQ1BQaG90b3Nob3AgSUNDIHByb2ZpbGUAAHjanVNnVFPpFj333vRCS4iAlEtvUhUIIFJCi4AU...",
  "secret": "JBSWY3DPEHPK3PXP"
}

Next Steps

1. Display the QR code to the user (decode the base64 PNG)
2. User scans QR code with their authenticator app (Google Authenticator, Authy, 1Password, etc.)
3. User enters the 6-digit TOTP code from their app
4. Call POST /mfa/setup/confirm with the secret and code to complete setup