Transactional OTP Engine

The GNS OTP engine provides hardened two-factor authentication, account verification, and payment confirmation workflows with sub-second delivery.

1. Security Architecture

• Zero Plaintext Storage: OTP codes are hashed with a server-side pepper and SHA-256 before storage in Redis.
• Short Time-to-Live (TTL): Codes automatically expire after a configurable window (default: 5 minutes / 300 seconds).
• Brute-Force Tombstoning: After 5 failed verification attempts, the verification key is permanently tombstoned, preventing any further guess attempts against that session.
• Database Persistence: Every OTP transaction is persisted to PostgreSQL (otp_transactions), ensuring complete auditability on the /activity feed.

2. Dispatching an OTP (POST /api/v1/otp/send)

curl -X POST "https://api.gns.iitdeveloper.com/api/v1/otp/send" \
-H "Authorization: Bearer gns_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
  "channel": "email",
  "recipient": "user@example.com",
  "length": 6,
  "ttl_seconds": 300
}'

{
  "status": "sent",
  "transaction_id": "otp_01J7M5QW8B9C0D1E2F3G4H5J6K",
  "recipient": "u***r@example.com",
  "channel": "email",
  "expires_in_seconds": 300
}

3. Verifying an OTP (POST /api/v1/otp/verify)

When the user submits the code on your frontend, send it to GNS for verification:

curl -X POST "https://api.gns.iitdeveloper.com/api/v1/otp/verify" \
-H "Authorization: Bearer gns_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
  "transaction_id": "otp_01J7M5QW8B9C0D1E2F3G4H5J6K",
  "code": "849201"
}'

{
  "status": "verified",
  "transaction_id": "otp_01J7M5QW8B9C0D1E2F3G4H5J6K",
  "verified_at": "2026-09-13T12:45:00Z"
}

4. Client-Supplied Custom Codes

Integrators with existing upstream auth or core banking engines can supply their own pre-generated code:

{
  "channel": "sms",
  "recipient": "+15551234567",
  "code": "SECURE-9921",
  "ttl_seconds": 180
}

[!IMPORTANT] The code parameter requires the otp:custom_code permission scope. Codes are restricted to [A-Za-z0-9-_] (4 to 16 characters) to protect against SMS header injection.