> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Verify MFA > Confirm a TOTP code against the pending secret, enable MFA, and receive one-time backup codes. Validates a TOTP code against the secret issued by [Begin MFA Setup](/api-reference/auth/mfa-setup), enables MFA for the logged-in user, and returns a fresh set of ten one-time backup codes. The backup codes are shown exactly once — only their hashes are stored — so display them to the user immediately. Any backup codes from a previous enrollment are replaced. After this call, logins complete via [Complete an MFA Login](/api-reference/auth/login-mfa). Requires a logged-in user session; API-key callers receive `401`. ## Body Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------------------- | | `code` | string | Yes | The current 6-digit TOTP code from the authenticator app. | ## Example Request ```bash theme={null} curl -X POST https://api.recurso.dev/v1/auth/mfa/verify \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{ "code": "482913" }' ``` ## Example Response ```json theme={null} { "mfa_enabled": true, "backup_codes": [ "K7Q2M-3XR4T", "P3ZH5-W6NDC", "A5YJ4-L2VB7", "T2RM6-Q3XKF", "G4WN2-H7PZD", "C6BV7-J5TAM", "X2LK6-N4RQW", "M5DF3-Z7HYB", "R5PT4-V2KCJ", "H3NX6-B2QLW" ] } ``` ## Fields | Field | Type | Description | | -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `mfa_enabled` | boolean | Always `true` on success. | | `backup_codes` | array of string | Ten one-time recovery codes, formatted `XXXXX-XXXXX`. Each can be used once in place of a TOTP code; they are not retrievable after this response. | ## Errors | Status | Code | When | Fix | | ------ | ------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | 400 | `validation_failed` | `code` is missing, or it does not match the pending secret (`invalid code`). | Send the current code from the authenticator; check the device clock. | | 401 | `unauthorized` | No live session cookie, or the caller authenticated with an API key rather than a user session. | Sign in via [`/auth/login`](/api-reference/auth/login) and send the `recurso_session` cookie. | | 409 | `conflict` | MFA is already enabled, or setup has not been started (no pending secret). | Call [Begin MFA Setup](/api-reference/auth/mfa-setup) first; if already enabled, no action is needed. | | 500 | `internal_error` | MFA could not be enabled or the backup codes could not be stored. | Retry; contact support if it persists. | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml POST /v1/auth/mfa/verify openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/auth/mfa/verify: post: tags: - Auth summary: Confirm and enable TOTP MFA description: > Validates a TOTP code against the pending secret, enables MFA, and returns a fresh set of one-time backup codes. The backup codes are shown exactly once — only their hashes are stored. operationId: mfaVerify requestBody: required: true content: application/json: schema: type: object required: - code properties: code: type: string responses: '200': description: MFA enabled; one-time backup codes returned. content: application/json: schema: type: object properties: mfa_enabled: type: boolean backup_codes: type: array items: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' security: - sessionCookie: [] components: responses: BadRequest: description: The request body or parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The request conflicts with current state (e.g. duplicate email, last owner). content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. sessionCookie: type: apiKey in: cookie name: recurso_session description: > Dashboard user session cookie (httpOnly) issued by `POST /auth/register` and `POST /auth/login`. v1 endpoints accept EITHER this cookie or the tenant API key (`bearerAuth`). ````