Authentication

Concepts

ELVA Notify uses application-level authentication. Every protected endpoint requires two fields in the JSON request body:

Credentials are not sent via Authorization headers. The middleware validateAppApiKey runs before OTP and Notify controllers.

Server-side credentials are loaded at startup from APP_CREDENTIALS_JSON:

{"enandi-app": "your-secret-key", "other-app": "another-secret"}

Implementation: src/config/allowedApps.js, src/middleware/validateAppApiKey.js.

Protected vs Unprotected Endpoints

Authentication Flow

Validation Decision Flow

appId Rules

From src/utils/appId.js:

• Must be a non-empty string after trim
• Must not contain : (colon) — reserved for Redis key structure
• Normalized to trimmed value for lookup and OTP storage

The appId in the request body determines the Redis namespace: otp:{appId}:{recipient}.

Real Request Example (valid)

{
  "appId": "enandi-app",
  "apiKey": "your-secret-key",
  "phone": "919876543210"
}

Real Response Example (missing apiKey)

{
  "success": false,
  "error": "unauthorized",
  "message": "API key is required",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Real Response Example (wrong key)

{
  "success": false,
  "error": "forbidden",
  "message": "Invalid app credentials",
  "requestId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

cURL Example

curl -X POST https://api.notify.elvatech.in/otp/send \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "enandi-app",
    "apiKey": "your-secret-key",
    "phone": "919876543210"
  }'

Global Rate Limiting (post-auth context)

After authentication, all routes pass through a global rate limiter (src/middleware/rateLimiter.js):

• 10 requests per minute per appId (or apiKey / client IP fallback)
• Exceeded limit returns 429 rate_limited

This is separate from OTP-specific per-phone limits documented in OTP API.

Troubleshooting Notes

Warnings

Always use HTTPS in production. Credentials in JSON body are visible on the wire without TLS.

Do not commit APP_CREDENTIALS_JSON to source control. Configure via deployment secrets.

Each appId is an OTP tenant. Using the same appId across unrelated products shares OTP state.

Related Configuration

If APP_CREDENTIALS_JSON is empty or unset, allowedApps is an empty object and all authenticated requests return 403 forbidden.