Request QR Code for MFA Setup
The GET /api/qrCode endpoint generates a QR code image used to set up Multi-Factor Authentication (MFA) for a user's account. Users scan the returned QR code with an authenticator app such as Google Authenticator to link their account and add a second verification step to the login process. This endpoint is called during the MFA enrollment flow before MFA is active on the account.
Endpoint
GET /api/qrCode
Authentication
Bearer token required. Obtain via:
POST https://api.banking.netevia.dev/api/auth/v2Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.
When to use
Use this endpoint when a user is enrolling in MFA for the first time or re-linking their authenticator app. The partner application should call this endpoint, display the returned QR code image to the user, and prompt them to scan it with their authenticator app. After scanning, the user's app will begin generating time-based one-time passwords (TOTP) that are required on subsequent logins.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| secret | string | No | The MFA secret key used to generate the QR code. If omitted, the server generates a new secret automatically. |
Response
200 OK
Returns a QR code image (typically PNG or base64-encoded image data) that the user scans with their authenticator app to complete MFA enrollment.
| Field | Type | Description |
|---|---|---|
| (image data) | binary / string | The QR code image returned by the server. The exact format depends on the Content-Type response header. |
{
"qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}Error Codes
| Code | When it happens |
|---|---|
| 400 | The secret query parameter is malformed or invalid |
| 401 | Token missing, expired, or invalid |
| 403 | Insufficient permissions to request an MFA QR code |
| 404 | User account not found |
| 500 | Internal server error |
Common Mistakes
- Passing a malformed or expired
secretvalue — if you are not managing the secret yourself, omit the parameter and let the server generate one. - Displaying the QR code after the user has already scanned it and confirmed MFA setup; once MFA is active, calling this endpoint again will regenerate the secret and invalidate the previous authenticator entry.
- Not storing the server-generated secret securely if you need to reference it later for account recovery flows.
Related Endpoints
POST /api/auth/v2— Obtain a Bearer token using username, password, and partnerIdPOST /api/auth/refresh— Refresh an existing Bearer token before it expires
Example
curl -X GET "https://api.banking.netevia.dev/api/qrCode?secret=YOUR_MFA_SECRET" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Accept: application/json"Success