openapi: 3.1.0
info:
  title: Bandwidth Multi-Factor Authentication API
  description: >-
    The Bandwidth Multi-Factor Authentication API allows developers to
    generate and verify secure MFA codes delivered via voice calls or SMS
    messages. It leverages Bandwidth's Voice and Messaging APIs under the
    hood, handling token generation and management automatically. Developers
    can customize the code length, expiration time, and delivery message
    template. The API supports both one-time passcode delivery and
    verification in a simple two-step workflow.
  version: '1.0'
  contact:
    name: Bandwidth Support
    url: https://support.bandwidth.com
  termsOfService: https://www.bandwidth.com/legal/
externalDocs:
  description: Bandwidth MFA API Documentation
  url: https://dev.bandwidth.com/docs/mfa/
servers:
  - url: https://mfa.bandwidth.com/api/v1
    description: Production Server
tags:
  - name: MFA
    description: >-
      Generate and verify multi-factor authentication codes via SMS
      messaging or voice calls. Supports customizable code length,
      expiration, and delivery templates.
security:
  - basicAuth: []
paths:
  /accounts/{accountId}/code/messaging:
    post:
      operationId: createMessagingMfa
      summary: Send MFA code via SMS
      description: >-
        Generates a multi-factor authentication code and delivers it to
        the specified phone number via SMS message. The code is
        automatically generated by Bandwidth and inserted into the
        message template at the {CODE} placeholder. The generated code
        can then be verified using the verify endpoint.
      tags:
        - MFA
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaMessagingRequest'
      responses:
        '200':
          description: MFA code sent successfully via SMS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaMessagingResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /accounts/{accountId}/code/voice:
    post:
      operationId: createVoiceMfa
      summary: Send MFA code via voice call
      description: >-
        Generates a multi-factor authentication code and delivers it to
        the specified phone number via an automated voice call. The code
        is read aloud using text-to-speech. The generated code can then
        be verified using the verify endpoint.
      tags:
        - MFA
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaVoiceRequest'
      responses:
        '200':
          description: MFA code sent successfully via voice call
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaVoiceResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /accounts/{accountId}/code/verify:
    post:
      operationId: verifyMfaCode
      summary: Verify MFA code
      description: >-
        Verifies a multi-factor authentication code that was previously
        sent to a user via SMS or voice. Returns whether the code is
        valid and has not expired.
      tags:
        - MFA
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaVerifyRequest'
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaVerifyResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using your Bandwidth API credentials.
        Use your API username and password from the Bandwidth Dashboard.
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      description: The unique identifier for the Bandwidth account
      schema:
        type: string
  schemas:
    MfaMessagingRequest:
      type: object
      required:
        - from
        - to
        - applicationId
        - message
        - digits
      properties:
        from:
          type: string
          description: >-
            The Bandwidth phone number to send the SMS from, in E.164 format
          example: '+19195551234'
        to:
          type: string
          description: >-
            The destination phone number to send the MFA code to, in
            E.164 format
          example: '+19195554321'
        applicationId:
          type: string
          description: >-
            The ID of the Bandwidth messaging application to use for
            sending the SMS
        scope:
          type: string
          description: >-
            An optional field to denote what scope or action the MFA
            code is for. This is returned during verification.
        message:
          type: string
          description: >-
            The message template to send. Use {CODE} as a placeholder
            for the generated MFA code.
          example: 'Your verification code is {CODE}'
        digits:
          type: integer
          minimum: 4
          maximum: 8
          description: >-
            The number of digits in the generated MFA code (4-8)
          example: 6
        expirationTimeInMinutes:
          type: number
          minimum: 1
          maximum: 15
          default: 3
          description: >-
            The time in minutes before the MFA code expires (1-15,
            default 3 minutes)
    MfaMessagingResponse:
      type: object
      properties:
        messageId:
          type: string
          description: >-
            The unique identifier for the SMS message sent with the MFA code
    MfaVoiceRequest:
      type: object
      required:
        - from
        - to
        - applicationId
        - message
        - digits
      properties:
        from:
          type: string
          description: >-
            The Bandwidth phone number to make the voice call from, in
            E.164 format
          example: '+19195551234'
        to:
          type: string
          description: >-
            The destination phone number to call with the MFA code, in
            E.164 format
          example: '+19195554321'
        applicationId:
          type: string
          description: >-
            The ID of the Bandwidth voice application to use for the call
        scope:
          type: string
          description: >-
            An optional field to denote what scope or action the MFA
            code is for
        message:
          type: string
          description: >-
            The message template spoken during the call. Use {CODE} as
            a placeholder for the generated MFA code.
          example: 'Your verification code is {CODE}'
        digits:
          type: integer
          minimum: 4
          maximum: 8
          description: >-
            The number of digits in the generated MFA code (4-8)
          example: 6
        expirationTimeInMinutes:
          type: number
          minimum: 1
          maximum: 15
          default: 3
          description: >-
            The time in minutes before the MFA code expires (1-15,
            default 3 minutes)
    MfaVoiceResponse:
      type: object
      properties:
        callId:
          type: string
          description: >-
            The unique identifier for the voice call made with the MFA code
    MfaVerifyRequest:
      type: object
      required:
        - to
        - code
        - expirationTimeInMinutes
      properties:
        to:
          type: string
          description: >-
            The phone number the MFA code was sent to, in E.164 format
          example: '+19195554321'
        scope:
          type: string
          description: >-
            The scope that was used when the code was generated. Must
            match for verification to succeed.
        code:
          type: string
          description: >-
            The MFA code entered by the user for verification
          example: '123456'
        expirationTimeInMinutes:
          type: number
          minimum: 1
          maximum: 15
          default: 3
          description: >-
            The expiration window to check against, in minutes
    MfaVerifyResponse:
      type: object
      properties:
        valid:
          type: boolean
          description: >-
            Whether the MFA code is valid and has not expired
    Error:
      type: object
      properties:
        type:
          type: string
          description: The error type identifier
        description:
          type: string
          description: A human-readable description of the error