openapi: 3.0.1 info: title: Evolution Foundation - Auth Service - Multi Factor Authentication description: Authentication and user and account management version: v1.0.0 servers: - url: https://api.evoai.app description: Production server - url: http://localhost:3001 description: Development server variables: port: default: '3001' - url: '{customUrl}' description: Custom server variables: customUrl: default: https://your-instance.com description: Enter your server URL paths: /api/v1/mfa/backup_codes: get: summary: Get MFA backup codes description: Retrieve current MFA backup codes operationId: getBackupCodes security: - ApiAccessTokenAuth: [] responses: '200': description: Backup codes retrieved successfully content: application/json: schema: $ref: '#/components/schemas/BackupCodesResponse' example: success: true data: backup_codes: [] meta: timestamp: '2026-01-28T22:25:48Z' message: Backup codes retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/backup_codes method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized access value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/backup_codes method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/backup_codes method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: mfa_not_enabled: summary: MFA not enabled value: success: false error: code: NOT_FOUND message: MFA is not enabled for this user meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/backup_codes method: GET user_not_found: summary: User not found value: success: false error: code: NOT_FOUND message: User not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/backup_codes method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/backup_codes method: GET /api/v1/mfa/disable: post: summary: Disable MFA description: Disable multi-factor authentication for the user operationId: disableMFA security: - ApiAccessTokenAuth: [] parameters: [] responses: '200': description: MFA disabled successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object description: Empty object indicating successful operation example: {} meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2026-01-28T22:32:23Z' message: type: string description: Success message example: MFA disabled successfully example: success: true data: {} meta: timestamp: '2026-01-28T22:32:23Z' message: MFA disabled successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_password: summary: Invalid password value: success: false error: code: VALIDATION_ERROR message: Invalid password meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/disable method: POST missing_password: summary: Password required value: success: false error: code: VALIDATION_ERROR message: Password is required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/disable method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized access value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/disable method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/disable method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: mfa_not_enabled: summary: MFA not enabled value: success: false error: code: NOT_FOUND message: MFA is not enabled for this user meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/disable method: POST user_not_found: summary: User not found value: success: false error: code: NOT_FOUND message: User not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/disable method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/disable method: POST requestBody: required: true content: application/json: schema: type: object properties: password: type: string description: Current user password for verification required: - password /api/v1/mfa/regenerate_backup_codes: post: summary: Regenerate MFA backup codes description: Generate new MFA backup codes (invalidates old ones) operationId: regenerateBackupCodes security: - ApiAccessTokenAuth: [] parameters: [] responses: '200': description: Backup codes regenerated successfully content: application/json: schema: $ref: '#/components/schemas/BackupCodesResponse' '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_password: summary: Invalid password value: success: false error: code: VALIDATION_ERROR message: Invalid password meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/regenerate_backup_codes method: POST missing_password: summary: Password required value: success: false error: code: VALIDATION_ERROR message: Password is required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/regenerate_backup_codes method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized access value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/regenerate_backup_codes method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/regenerate_backup_codes method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: mfa_not_enabled: summary: MFA not enabled value: success: false error: code: NOT_FOUND message: MFA is not enabled for this user meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/regenerate_backup_codes method: POST user_not_found: summary: User not found value: success: false error: code: NOT_FOUND message: User not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/regenerate_backup_codes method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/regenerate_backup_codes method: POST requestBody: required: true content: application/json: schema: type: object properties: password: type: string description: Current user password for verification required: - password /api/v1/mfa/setup_email_otp: post: summary: Setup Email OTP authentication description: Setup Email-based One-Time Password authentication operationId: setupEmailOTP security: - ApiAccessTokenAuth: [] parameters: [] responses: '200': description: Email OTP setup successful content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object description: Empty object example: {} meta: type: object properties: timestamp: type: string format: date-time example: '2026-02-26T21:26:26Z' message: type: string example: Email OTP sent successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_password: summary: Invalid password value: success: false error: code: VALIDATION_ERROR message: Invalid password or Email OTP already enabled meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_email_otp method: POST email_otp_already_enabled: summary: Email OTP already enabled value: success: false error: code: VALIDATION_ERROR message: Email OTP is already enabled for this user meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_email_otp method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized access value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_email_otp method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_email_otp method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: User not found value: success: false error: code: NOT_FOUND message: User not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_email_otp method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_email_otp method: POST requestBody: required: true content: application/json: schema: type: object properties: password: type: string description: Current user password for verification required: - password /api/v1/mfa/setup_totp: post: summary: Setup TOTP authentication description: Setup Time-based One-Time Password (TOTP) authentication operationId: setupTOTP security: - ApiAccessTokenAuth: [] parameters: [] responses: '200': description: TOTP setup successful content: application/json: schema: $ref: '#/components/schemas/MFASetupResponse' '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_password: summary: Invalid password value: success: false error: code: VALIDATION_ERROR message: Invalid password or TOTP already enabled meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_totp method: POST totp_already_enabled: summary: TOTP already enabled value: success: false error: code: VALIDATION_ERROR message: TOTP is already enabled for this user meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_totp method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized access value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_totp method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_totp method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: User not found value: success: false error: code: NOT_FOUND message: User not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_totp method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/setup_totp method: POST requestBody: required: true content: application/json: schema: type: object properties: password: type: string description: Current user password for verification required: - password /api/v1/mfa/verify_email_otp: post: summary: Verify Email OTP code description: Verify Email OTP code sent to user email operationId: verifyEmailOTP security: - ApiAccessTokenAuth: [] parameters: [] responses: '200': description: Email OTP verification successful headers: access-token: schema: type: string description: Authentication token (if login) client: schema: type: string description: Client identifier uid: schema: type: string description: User identifier content: application/json: schema: $ref: '#/components/schemas/MFAVerifyResponse' '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_email_otp_code: summary: Invalid Email OTP code value: success: false error: code: VALIDATION_ERROR message: Invalid Email OTP code meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_email_otp method: POST missing_fields: summary: Missing required fields value: success: false error: code: VALIDATION_ERROR message: Email and OTP code are required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_email_otp method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized access value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_email_otp method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_email_otp method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: user_not_found: summary: User not found value: success: false error: code: NOT_FOUND message: User not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_email_otp method: POST email_otp_not_setup: summary: Email OTP not setup value: success: false error: code: NOT_FOUND message: Email OTP is not setup for this user meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_email_otp method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_email_otp method: POST requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: User email address example: user@example.com otp_code: type: string description: OTP code received via email example: '123456' required: - email - otp_code /api/v1/mfa/verify_totp: post: summary: Verify TOTP code description: Verify TOTP code during login or setup confirmation operationId: verifyTOTP security: - ApiAccessTokenAuth: [] parameters: [] responses: '200': description: TOTP verification successful headers: access-token: schema: type: string description: Authentication token (if login) client: schema: type: string description: Client identifier uid: schema: type: string description: User identifier content: application/json: schema: $ref: '#/components/schemas/MFAVerifyResponse' '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_totp_code: summary: Invalid TOTP code value: success: false error: code: VALIDATION_ERROR message: Invalid TOTP code meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_totp method: POST missing_fields: summary: Missing required fields value: success: false error: code: VALIDATION_ERROR message: Email and OTP code are required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_totp method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized access value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_totp method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_totp method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: user_not_found: summary: User not found value: success: false error: code: NOT_FOUND message: User not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_totp method: POST totp_not_setup: summary: TOTP not setup value: success: false error: code: NOT_FOUND message: TOTP is not setup for this user meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_totp method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/mfa/verify_totp method: POST requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: User email address example: user@example.com otp_code: type: string description: 6-digit TOTP code pattern: ^[0-9]{6}$ example: '123456' required: - email - otp_code components: schemas: BackupCodesResponse: type: object properties: success: type: boolean example: true data: type: object properties: backup_codes: type: array items: type: string description: Array of backup codes example: [] meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2026-01-28T22:25:48Z' message: type: string description: Success message example: Backup codes retrieved successfully ErrorResponse: type: object required: - success - error - meta properties: success: type: boolean example: false error: type: object required: - code - message properties: code: type: string example: VALIDATION_ERROR message: type: string example: Validation failed details: type: object additionalProperties: true nullable: true meta: type: object required: - timestamp - path - method properties: timestamp: type: string format: date-time example: '2024-01-15T10:30:00Z' path: type: string example: /api/v1/super_admin/accounts/123 method: type: string example: POST MFASetupResponse: type: object properties: success: type: boolean example: true data: type: object properties: secret: type: string description: TOTP secret (only for TOTP setup) qr_code_url: type: string description: QR code URL (only for TOTP setup) backup_codes: type: array items: type: string description: MFA backup codes message: type: string MFAVerifyResponse: type: object properties: success: type: boolean example: true data: type: object properties: mfa_confirmed: type: boolean user: $ref: '#/components/schemas/User' message: type: string User: type: object properties: id: type: string format: uuid name: type: string email: type: string format: email type: type: string enum: - User - SuperAdmin role: type: object nullable: true properties: id: type: string format: uuid key: type: string name: type: string pubsub_token: type: string display_name: type: string nullable: true availability: type: string enum: - online - busy - offline mfa_enabled: type: boolean confirmed: type: boolean custom_attributes: type: object additionalProperties: true ui_settings: type: object additionalProperties: true is_super_admin: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time securitySchemes: DeviseTokenAuth: type: apiKey in: header name: access-token description: Devise Token Auth - requires access-token, client, and uid headers BearerAuth: type: http scheme: bearer bearerFormat: JWT SuperAdminAuth: type: apiKey in: header name: api_access_token description: Super Admin authentication token ApiAccessTokenAuth: type: apiKey in: header name: api_access_token description: API access token authentication