One-Time Password quick start guide
All you need to know before you set up and send One-Time Passwords
A one-time password (OTP) is used for secure user authentication. It provides a temporary, unique code to verify identity during login, transactions, or other sensitive operations, enhancing protection against unauthorised access. Currently, OTPs are supported via SMS only.
Key Features
- OTP Generation and Delivery: Generate one-time passwords and deliver them to user mobile numbers via SMS.
- Verification: Validate OTP codes provided by users against the original request.
- SIM Swap Protection: Optional feature to prevent OTP delivery to numbers recently associated with SIM swaps.
- Dedicated Queue: Ensures OTP messages are prioritised over marketing communications for prompt delivery.
- Customisation: Configure OTP type (numeric or alphanumeric), length, and expiration time.
- Real-time Reporting: Access logs and delivery reports for complete visibility.
- API Authorisation: OAuth-secured endpoints for seamless integration.
Use Cases
- User Authentication: Enhance login security by requiring OTP verification.
- Transactional Security: Confirm high-value or sensitive transactions.
- Account Recovery: Simplify and secure password reset processes.
Prerequisites for Setting Up One-Time Passwords (OTP)
- Active SMS Gateway: Confirm with your Account Manager that your SMS setup is configured to support OTP functionality.
- Mobile Numbers in E.164 Format: Provide recipient mobile numbers in the internationally standardised E.164 format (e.g., +353123456789).
- **API Credentials:** Obtain valid OAuth 2.0 credentials for authentication if using API endpoints for OTP generation and verification.
- SIM Swap Service (Optional): If using SIM Swap Protection, ensure integration with the relevant service.
Getting Started with One-Time Password Integration
The first step to use the OTP feature is to activate and configure the OTP integration by navigating to Settings → Integrations → Marketplace, selecting the OTP integration, and clicking Connect New. Full instructions can be found here.
In the Marketplace Integration, you can enable and configure the One-Time Password (OTP) feature, customise settings like OTP type, length, and lifetime, and create SMS content.
Set up and configure the APIs for OTP generation and verification
This involves:
Generate API: Configure the /otp/generate endpoint to create and send OTPs with parameters like user ID, mobile number, or email.
Verify API: Configure the /otp/verify endpoint to validate OTPs with parameters like request_id and the user-provided OTP.
During the API setup, you must whitelist the necessary IPs to ensure secure communication between your systems and Xtremepush.
Reviewing Logs and Troubleshooting
Check the OTP History Tab for logs related to generation, delivery, and verification to ensure proper functionality.
Navigate to Settings > Integrations > One-Time Password > History tab in the Xtremepush platform.
Use the search functionality to filter records by:
Profile ID: Identify specific users linked to OTP activities.
Request Date: Locate logs for a specific time frame.
OTP ID: Track a unique OTP record.
Identifier Type & Value: Find records using user-specific identifiers (e.g., userid, customer_id, or email).
Examine the columns for key information:
Request Timestamp: When the OTP was generated.
Sent: Whether the OTP SMS was successfully sent (Yes/No).
Verified Timestamp: When the OTP was successfully verified.
Error: Any errors encountered during generation or verification.
Click on the Profile ID icon to navigate to the associated user profile for deeper investigation.
Error Codes
| Error Code | Description |
|---|---|
| OTP_EXPIRED | The OTP has exceeded its validity period and is no longer valid for verification. |
| OTP_INVALID | The user entered an incorrect OTP. |
| RETRY_LIMIT_EXCEEDED | The maximum allowed retry attempts for OTP verification have been exceeded. |
| DELIVERY_FAILED* | The OTP SMS could not be delivered to the recipient due to network issues or invalid numbers. * Only when delivery receipts are enabled |
One-Time Password Export Methods
Fetch OTP History Records List: Retrieve OTP history records with filtering and ordering options.
Fetch OTP History Record Info: Get detailed information for a specific OTP record.
OTP Automated History Export
Enables scheduled exports of OTP history via email or file storage.
How to Set Up OTP History Export
- Navigate to: Automations → Exports → Create/Edit Export
- Select Export Type:
- In the Data Type dropdown, choose "OTP History" (available only if an active OTP integration exists).
- Proceed with the configuration by selecting the required Integration and Segment.
- Schedule and Save the export to automate data retrieval.
For more details on automation exports, refer to the Automations Guide.
Note: If an OTP integration is removed, the export will display its ID instead of the name.
FAQ - One-Time Password (OTP)
Common Questions
What is the expiration time for OTPs?
The default expiration time for OTPs can be configured during setup. Typically, it ranges from 5 to 15 minutes, depending on your security requirements.Can OTP messages be customised?
Yes, OTP messages can be customised in the platform when creating an OTP Integration. Ensure the message remains clear and includes the OTP code prominently.What happens if the OTP delivery fails?
If OTP delivery fails, the system retries based on your retry policy configuration. If the retries fail, you can review the issue using the OTP history.How does SIM Swap Protection work?
When enabled SIM Swap Protection ensures OTPs are sent only to trusted numbers. If a SIM swap is detected, the OTP will not be delivered, and an alternative action can be triggered.Is the OTP case-sensitive?
Yes, the OTP is case-sensitive. Users must enter the code exactly as received, including uppercase and lowercase characters, to ensure successful verification.Updated 3 days ago