API integration guide

What is Octotp?

Octotp is an API for one-time verification codes. This guide shows you how to integrate it into your application.

Prerequisites

• An Octotp account
• A project with an API key (from the dashboard)

How it works

1. Create a token – send the recipient’s email or phone, receive a code.
2. Deliver the code – use your email or SMS provider.
3. Validate the token – when the user enters the code, call the validate endpoint.

Create a token

Endpoint: POST /api/tokens

Headers:

• Content-Type: application/json
• X-Api-Key: <your_api_key>

Request body:

{
  "projectId": "your-project-guid",
  "recipientEmail": "user@example.com",
  "recipientPhone": null,
  "expiresInSeconds": 300
}

Use either recipientEmail or recipientPhone, not both. Omit expiresInSeconds to use the default (300 seconds = 5 minutes).

Response:

{
  "code": "123456",
  "expiresAt": "2026-02-14T12:05:00Z"
}

Store the code securely and deliver it to your user. Do not log or expose it unnecessarily.

Validate a token

Endpoint: POST /api/tokens/validate

Headers:

• Content-Type: application/json
• X-Api-Key: <your_api_key>

Request body:

{
  "projectId": "your-project-guid",
  "recipientEmail": "user@example.com",
  "recipientPhone": null,
  "code": "123456"
}

The recipient (email or phone) must match the one used when creating the token.

Response:

{
  "isValid": true
}

If the code is wrong, expired, or already used, isValid will be false.

Error handling

• 401 Unauthorized: Invalid or missing API key.
• 403 Forbidden: API key does not match the project ID in the request.
• 429 Too Many Requests: Rate limit exceeded. Wait and retry.

Best practices

1. Match recipient: Always use the same email or phone for create and validate.
2. Single use: Each token works only once. Create a new one if the user needs to try again.
3. Expiry: Default 5 minutes is usually sufficient. Shorter for high-security flows.
4. Rate limits: The free tier allows 60 tokens per minute. Plan for bursts.

Next steps

• How it works – overview of the flow
• Use cases – email verification, 2FA, password reset
• Pricing – plans and limits