Flow2FA OTP API

OpenAPI specification

The endpoints on this page are also published as a machine-readable OpenAPI 3.1 document. Use it to generate client SDKs, import the API into Postman or Insomnia, or drive contract tests. It describes only the public REST surface documented here — SMPP v3.4 connections are provisioned separately during account setup.

curl -sS https://flow2fa.com/openapi.json -o flow2fa-openapi.json

Authentication

Both endpoints require your API key in the request headers. Keep the key server-side — never ship it to a browser or mobile client.

x-api-key: YOUR_API_KEY
Content-Type: application/json

SMPP v3.4 connection setup

SMPP connections are provisioned during account setup. To begin, request and complete the Flow2FA SMPP connection form by emailing devs@flow2fa.com. If your deployment requires a VPN, we may also ask you to complete our VPN form. VPN setup may incur an additional setup charge and will be subject to implementation lead times. Connection details, security requirements, networking arrangements and applicable commercial terms will be confirmed during account setup.

Generates a One-Time Passcode and queues it for delivery via the selected channel. For security, the OTP value is never returned — only metadata and the otpId.

Request body (JSON)

Example request (illustrative values)

curl --location 'https://api.flow2fa.com/otp/generate' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "channel": "email",
  "provider": "YOUR_CONFIGURED_PROVIDER",
  "destination": "test@email.com",
  "type": "alphanumeric",
  "length": 8,
  "expiresInSeconds": 300,
  "templateId": "otp-default-a1562ab2"
}'

Successful response

{
  "otpId": "51a6fcc7-efc8-4e69-8bc1-ebb999befb2c",
  "destination": "test@email.com",
  "createdAt": "2025-09-10T14:05:41.5251815Z",
  "expiresAt": "2025-09-10T14:10:41.5251815Z"
}

Error messages

Validates a previously generated OTP using the otpId and the user-entered otp. On success the OTP is consumed (single use) and cannot be reused.

Request body (JSON)

Example request (illustrative values)

curl --location 'https://api.flow2fa.com/otp/validate' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "otpId": "c4f8814c-7a9d-4e13-b7d8-d4e66d272611",
  "otp": "z4dGyBPQ"
}'

Successful response (200)

{
  "success": true,
  "message": "OTP validated successfully."
}

Error messages

If the allowed attempt count configured for your account and provider value is exceeded, further validations return Too many failed attempts. Try again later. — even when the OTP is correct — until the lock duration elapses.

Notes & best practices

• The OTP value is not returned by the API. How code values are stored, hashed and retained is confirmed during security review rather than stated here.
• For sms, use E.164 format (e.g. +573001112233).
• A successful validation invalidates the OTP immediately; codes are single use.
• You do not need to send destination when validating — the otpId carries the context.
• Call both endpoints from your backend so the API key is never exposed.