API Authentication — OTP.ID Bearer Key Setup Guide

Every request you make to the OTP.ID API must be authenticated with an API key. OTP.ID uses the standard HTTP Bearer token scheme — you include your key in the Authorization header, and OTP.ID validates it before processing the request. There are no cookies, sessions, or OAuth flows to configure. If the key is valid, the request proceeds; if not, you receive a clear error response telling you exactly what went wrong.

Keep your API key secret. Never expose it in client-side code, browser JavaScript, mobile app binaries, or public repositories. If a key is compromised, rotate it immediately from your dashboard.

Get Your API Key

Your API key lives in the OTP.ID dashboard:

Log in at https://app.otp.id.
Open the Integration page.
In the API Key card, click Reveal — the key is displayed with a copy button. The key is masked again when you close the dialog.

The API key is a UUID string (e.g. 550e8400-e29b-41d4-a716-446655440000). You can reveal it again at any time from the Integration page. To rotate the key, click Rotate API Key in the same card and confirm the action. The old key stops working immediately — update every integration right away.

Each merchant account has exactly one active API key. All credit deductions, rate limits, and transaction records are tracked against your account. There is no multi-key or per-environment key management — if you need isolated environments, use separate merchant accounts.

Include the Key in Every Request

Pass your API key as a Bearer token in the Authorization header on every request to any /v3/* endpoint:

Authorization: Bearer YOUR_API_KEY

Here’s a minimal example with curl:

curl -X POST https://api.otp.id/v3/request \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "destination": "6281234567890",
    "brand": "MyApp"
  }'

Code Examples

The following examples show how to attach the Authorization header when making requests from common environments.

const response = await fetch('https://api.otp.id/v3/request', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel: 'whatsapp',
    destination: '6281234567890',
    brand: 'MyApp'
  })
});

const result = await response.json();

if (result.success) {
  console.log('OTP sent:', result.data.otp_id);
} else {
  console.error('Error:', result.error.code, result.error.message);
}

import requests

response = requests.post(
    'https://api.otp.id/v3/request',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'channel': 'whatsapp',
        'destination': '6281234567890',
        'brand': 'MyApp'
    }
)

result = response.json()

if result['success']:
    print('OTP sent:', result['data']['otp_id'])
else:
    print('Error:', result['error']['code'], result['error']['message'])

curl -X POST https://api.otp.id/v3/request \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "destination": "6281234567890",
    "brand": "MyApp"
  }'

Authentication Errors

All authentication failures return HTTP 401 with success: false. The error.code is always "UNAUTHORIZED", and error.message describes the specific problem. IP allowlisting is a separate control from API-key authentication. If it is enabled for your merchant, a valid key can still receive HTTP 403 with IP_NOT_ALLOWED when the request comes from an unlisted server IP. See the API V3 IP allowlist guide.

Missing or Malformed Authorization Header

If you omit the Authorization header entirely, or its value does not start with Bearer :

{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Sertakan header Authorization: Bearer <api_key>"
  }
}

Empty API Key

If you include the header but provide an empty string as the token:

{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key kosong"
  }
}

Unknown or Invalid API Key

If the key is present but does not match any active key in OTP.ID’s system:

{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key tidak dikenal"
  }
}

This error also occurs after the key has been rotated (the old key is invalid immediately). If you receive it unexpectedly, view the current key in your dashboard and confirm you’re not accidentally including extra whitespace or a newline character in the header value.

Best Practices

Use environment variables to store your API key rather than hardcoding it in source files. Reference it as process.env.OTPID_API_KEY (Node.js) or os.environ["OTPID_API_KEY"] (Python).
Rotate the key periodically — and immediately if you suspect exposure. Remember that rotation invalidates the old key at once, so coordinate the update across your services.
Call the API from your server only. Because your account has a single key, treating it as a server-side secret is essential — never ship it to browsers or mobile apps.
Monitor last_balance in send responses to detect unexpected usage spikes that could indicate a leaked key.

Get Started

Core Concepts

Channel Guides

Guides

Reference

API Authentication — OTP.ID Bearer Key Setup Guide

Get Your API Key

Include the Key in Every Request

Code Examples

Authentication Errors

Missing or Malformed Authorization Header

Empty API Key

Unknown or Invalid API Key

Best Practices

​Get Your API Key

​Include the Key in Every Request

​Code Examples

​Authentication Errors

​Missing or Malformed Authorization Header

​Empty API Key

​Unknown or Invalid API Key

​Best Practices

Get Your API Key

Include the Key in Every Request

Code Examples

Authentication Errors

Missing or Malformed Authorization Header

Empty API Key

Unknown or Invalid API Key

Best Practices