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 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