OTP Verification Shared Service API

The OTP Shared Service manages the generation, anti-brute-force rate-limiting, and verification of one-time passcodes over SMS and Email.

For a Node.js backend, use api.otp.generate(...) and api.otp.verify(...) from the APICenter SDK. The client requires an idempotency key for both mutations.

Service Specifications

• Base Route: /api/v1/shared/otp
• Required Header: Authorization: Bearer <SERVICE_ACCESS_TOKEN>
• Required Header: Idempotency-Key: <16–255 characters>

Use a separate key for each generate or verify request. Reusing the same key and body replays its original status and response for seven days. A changed body returns 409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH; a concurrent request returns 409 IDEMPOTENCY_KEY_IN_PROGRESS. If OTP delivery or verification has an uncertain outcome, APICenter returns 409 IDEMPOTENCY_OUTCOME_UNKNOWN on retry and keeps the key blocked for reconciliation.

1. Generate OTP

• Endpoint: POST /api/v1/shared/otp/generate

Request Body (OtpGenerateRequest)

{
  "recipient": "+639171234567",
  "channel": "sms",
  "digits": 6,
  "ttlSeconds": 300
}

Response (OtpGenerateResponse) — 201 Created

{
  "success": true,
  "data": {
    "otpId": "otp_9918231a48f29d10a9f",
    "expiresAt": "2026-07-31T23:25:00.000Z",
    "channel": "sms",
    "recipient": "+639171234567",
    "target": "+639171234567"
  }
}

2. Verify OTP

• Endpoint: POST /api/v1/shared/otp/verify

Request Body (OtpVerifyRequest)

{
  "otpId": "otp_9918231a48f29d10a9f",
  "code": "849201"
}

Response (OtpVerifyResponse) — 200 OK

{
  "success": true,
  "data": {
    "verified": true,
    "otpId": "otp_9918231a48f29d10a9f",
    "target": "+639171234567",
    "channel": "sms"
  }
}

3. Get OTP Status

• Endpoint: GET /api/v1/shared/otp/status/:otpId

Response — 200 OK

{
  "success": true,
  "data": {
    "otpId": "otp_9918231a48f29d10a9f",
    "status": "pending",
    "target": "+639171234567",
    "channel": "sms",
    "expiresAt": "2026-07-31T23:25:00.000Z"
  }
}