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.
openapi: 3.1.0
info:
title: Bandwidth Emergency Calling Available Numbers MFA API
description: The Bandwidth Emergency Calling API provides programmatic access to provision and manage 911 endpoints and locations for emergency services routing. It supports Dynamic Location Routing (DLR) for real-time address validation and location updates, ensuring compliance with Kari's Law and RAY BAUM's Act requirements. Bandwidth is the only CPaaS provider that also operates its own emergency services network, providing direct connectivity to public safety answering points (PSAPs) across the United States and Canada.
version: '1.0'
contact:
name: Bandwidth Support
url: https://support.bandwidth.com
termsOfService: https://www.bandwidth.com/legal/
servers:
- url: https://dashboard.bandwidth.com/api
description: Production Server
security:
- basicAuth: []
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.
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:
schemas:
MfaMessagingResponse:
type: object
properties:
messageId:
type: string
description: The unique identifier for the SMS message sent with the MFA code
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)
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
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
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
parameters:
accountId:
name: accountId
in: path
required: true
description: The unique identifier for the Bandwidth account
schema:
type: string
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic Authentication using your Bandwidth Dashboard API credentials.
externalDocs:
description: Bandwidth Emergency Calling API Documentation
url: https://dev.bandwidth.com/docs/emergency/emergencyCallingApi/