Authentication

All SecureOTP API endpoints require authentication. Public OTP endpoints (send and verify) use API key authentication via the Authorization header.

API Keys

SecureOTP uses API keys with a prefixed format to distinguish environments:

| Prefix | Environment | Behaviour | | --- | --- | --- | | sk_test_... | Sandbox | Simulates delivery, no real messages sent, no balance deducted | | sk_live_... | Live | Sends real messages, deducts credits from your balance |

Making Authenticated Requests

Include your API key as a Bearer token in the Authorization header of every request:

bash

curl -X POST https://otp.applicanity.com/api/v1/otp/sms/send \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+628123456789" }'

In JavaScript:

javascript

const response = await fetch('/api/v1/otp/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SECUREOTP_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ phone: '+628123456789' }),
})

Managing API Keys

API keys are managed from the Console under API Tokens.

Creating a Key

bash

curl -X POST https://otp.applicanity.com/api/token \
  -H "Authorization: Bearer <console_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "environment": "LIVE",
    "allowedDomains": "example.com,api.example.com"
  }'

The full key is returned only once at creation time. Copy and store it securely — it cannot be retrieved again.

json

{
  "token": {
    "id": 1,
    "name": "Production Backend",
    "key": "sk_live_abc123def456...",
    "environment": "LIVE",
    "active": true,
    "allowedDomains": "example.com,api.example.com",
    "createdAt": "2026-06-09T08:00:00.000Z"
  }
}

Revoking a Key

To revoke (deactivate) a key without deleting it:

bash

curl -X PUT https://otp.applicanity.com/api/token/1 \
  -H "Authorization: Bearer <console_session_token>"

A revoked key immediately returns 401 Unauthorized on all subsequent requests.

Deleting a Key

bash

curl -X DELETE https://otp.applicanity.com/api/token/1 \
  -H "Authorization: Bearer <console_session_token>"

Error Responses

| Status | Error | Cause | | --- | --- | --- | | 401 | Missing or invalid Authorization header | No Authorization header, or not in Bearer format | | 401 | Invalid API key | Key not found in the database | | 401 | API key has been revoked | Key exists but has been deactivated | | 403 | Account suspended | Your account has been suspended by an admin |

Security Best Practices

Store API keys in environment variables, never in source code
Use sk_test_... keys during development and CI — they cost nothing
Create separate keys for each environment (staging, production)
Rotate keys periodically by creating a new one and revoking the old one
Use allowedDomains to restrict which origins can use a given key