Documentation: Retrieving OTP Sent by SMS with HTTP API

This document provides instructions for retrieving a One-Time Password (OTP) sent via SMS using the OTP Device Sync HTTP API. This approach is suited for automated testing workflows that require SMS-based OTPs to verify two-factor authentication (2FA) functionality.

API Endpoint

Endpoint URL:

GET {API_BASE_URL}/retrieve/sms

This endpoint retrieves the OTP sent by SMS to a specified user (phone number) from a specified service (sender).

Request Parameters

• phone: string (required)
  The phone number of the user receiving the OTP.
• from: string (required)
  The identifier for the service sending the OTP, typically the name or number of the sender.
• registeredKey: string (required)
  The unique key required to authenticate and authorize the request.

Example Query:

GET {API_BASE_URL}/retrieve/sms?phone=+1234567890&from=ServiceName&registeredKey=YOUR_REGISTERED_KEY

Response

The API returns a JSON response containing the OTP.

Success Response:

{
  "code": "123456"  // The OTP code sent by SMS
}

Error Response: In case of an error, the API will return a 4xx or 5xx status code with an error message.

{
  "error": "Invalid registeredKey or missing parameters"
}

Example Usage

The following example demonstrates how to retrieve an SMS OTP using JavaScript (Node.js) with the Fetch API.

const fetch = require('node-fetch');

const getSMSOTP = async (phone, from, registeredKey) => {
  const url = new URL(`${process.env.API_BASE_URL}/retrieve/sms`);
  url.searchParams.append('phone', phone);
  url.searchParams.append('from', from);
  url.searchParams.append('registeredKey', registeredKey);

  try {
    const response = await fetch(url);
    if (response.ok) {
      const data = await response.json();
      console.log(`Retrieved SMS OTP: ${data.code}`);
      return data.code;
    } else {
      const errorText = await response.text();
      throw new Error(`Error retrieving SMS OTP: ${errorText}`);
    }
  } catch (error) {
    console.error(`Failed to fetch SMS OTP: ${error.message}`);
    throw error;
  }
};

// Usage example:
getSMSOTP("+1234567890", "ServiceName", "YOUR_REGISTERED_KEY");

Key Points

• Time Sensitivity: Retrieve the OTP quickly, as it may have a limited validity period.
• Authentication: Store the registeredKey securely to protect access.
• Error Handling: Implement error handling to capture any issues during retrieval, such as network errors or invalid parameters.

Summary

Using the HTTP API to retrieve SMS-based OTPs simplifies 2FA automation testing by allowing quick OTP access through the retrieve/sms endpoint. This API is easy to integrate into automated tests, ensuring that SMS OTP retrieval works consistently and efficiently in end-to-end testing scenarios.