What is the MITTO 2FA API?

Mitto’s two-factor authentication (2FA) API lets you send One Time Passwords (OTPs) using SMS or text-to-speech (TTS). Add a second layer of security to your applications with the 2FA API. The flexibility of multiple delivery methods ensures your users get their OTP.

2FA works like this:

1. The user visits your website or mobile app. They attempt to log in, authorize a transaction, or perform an action requiring 2FA. Your application has the user’s phone number.
2. Prompt the user to enter a One Time Password (OTP) sent via SMS or TTS.
3. Send the user a 4 to 10-digit verification code via SMS or TTS. Wait for them to enter it in your application.
4. The user enters the OTP. Check that it matches the verification code.
5. Retrieve details about the transaction using Mitto’s session detail records.

Documentation Organization

We organize our documentation as follows:

• Read details about endpoints and authentication. See a sample request and a response. – 2FA API
• See a list of use cases for the API. – 2FA API Use Cases
• Review API details, such as request and response parameters. – 2FA API Reference

Get Started with Mitto 2FA

This section provides general information about the Mitto 2FA API such as endpoints, methods, and response format and also discusses the related concept of callbacks / delivery reports.

Sign up for a Mitto Account

To get started with Mitto, do the following:
1. Sign up for a Mitto account at https://www.mitto.ch/contact/ or write to info@mitto.ch.
2. Submit the IPs you want to use for requests. They must be whitelisted on Mitto’s system.
3. For callbacks, provide your dedicated callback URL and method (both GET and POST methods are supported). Alternatively, you can use dynamic callbacks. See Replace Callback URL in an API Call for more details.
4. Mitto will respond with your account ID, API key, and confirmation that your IP addresses and callback URL are configured.

Request Requirements

There are different endpoints in the Mitto 2FA API:

Send an OTP

Send a POST request for an OTP to be sent to a particular number with this endpoint:
https://cpaas.mittoapi.com/2fa/send

Cancel an OTP You Sent

Send a POST request to cancel an OTP you’ve sent with this endpoint:
https://cpaas.mittoapi.com/2fa/cancel

Verify an OTP

Send a POST request to verify that a code was sent through SMS, phone call or email to the destination. Use this endpoint:
https://cpaas.mittoapi.com/2fa/verify

Retrieve Session Detail Records

For reviewing session detail records, you can send a POST request with filtering options with this endpoint:
https://cpaas.mittoapi.com/2fa/search

You can send a GET request to get all session detail records (SDRs) with this endpoint:
https://cpaas.mittoapi.com/2fa/search

You can send a GET request to search for information about a specific OTP with this endpoint:
https://cpaas.mittoapi.com/2fa/search/{OTPSid}

API Usage

For API usage information, send a GET request for an exhaustive list of all existing records associated with your 2FA account credentials with this endpoint: https://cpaas.mittoapi.com/2fa/usage/records

To filter records associated with your 2FA account credentials, send a POST request with your filter choices to this endpoint:
https://cpaas.mittoapi.com/2fa/usage/records

To filter usage records by blocks of time like daily, monthly, or yearly, send a GET request with this endpoint:
https://cpaas.mittoapi.com/2fa/usage/records/{subresource}

You can also include filters for this GET request.

Limit API Use

Limits let you enforce limitations on the number of OTPs sent based on various keys you choose like phone number, end user IP address and more.

Set limits by sending a POST request with this endpoint: https://cpaas.mittoapi.com/2fa/limits

You can update limits with a PUT request with this endpoint:
https://cpaas.mittoapi.com/2fa/limits/{limitSid}

Delete limits with a DELETE request with this endpoint:
https://cpaas.mittoapi.com/2fa/limits/{limitSid}

You can get a list of all the limits you’ve created with a GET request with this endpoint:
https://cpaas.mittoapi.com/2fa/limits/search

For details about a specific limit, send a GET request to:
https://cpaas.mittoapi.com/2fa/limits/{limitSid}

Create Workflow

The create workflow endpoint is called to create a new workflow for a given account. Send a POST request to:
https://cpaas.mittoapi.com/2fa/workflows

Update a Workflow

The update workflow endpoint lets you update an existing workflow for an existing account. Send a PUT request to:
https://cpaas.mittoapi.com/2fa/workflows/{workflowSid}

Delete a Workflow

The delete workflow endpoint is called to delete an existing workflow for an account. Send a DELETE request to:
https://cpaas.mittoapi.com/2fa/workflows/{workflowSid}

Get a List of Workflows

The list workflows endpoint lets you list all workflows associated with an account or sub-account. Send a GET request to:
https://cpaas.mittoapi.com/2fa/workflows/search

Get a Single Workflow

Retrieve details about a single workflow with a GET request to:
https://cpaas.mittoapi.com/2fa/workflows/search/{WorkflowSid}

For more details about request and response parameters for these endpoints, refer to 2FA API Reference. For more details about use cases with example request and responses, refer to 2FA Use Cases.

Response Format and Content

The response is returned in JSON data format. It is recommended to enforce the format (see “Endpoint and Method”) to make sure the correct format is received. The response format can be JSON or XML.

The response information varies depending on what endpoint you are using. For more information about responses, refer to
For more details about response parameters, refer to the response information in 2FA API Reference. For more details about use cases with example request and responses, refer to 2FA Use Cases.

Authentication

Mitto’s 2FA API uses basic authentication for each request. Basic authentication is a simple authentication method that’s built into the HTTP protocol. You send HTTP requests with an Authorization header formatted like so:
Authorization: Basic base64(accountID:API key)

In the example, you would replace base64(accountID:API key) with a base64-encoded string where the string consisted of “accountID:API key”.

For examples of requests using basic authentication, refer to 2FA Use Cases, where all examples use this authentication method.