Authentication & Security

Sendrin implements two authentication tiers depending on the operation:

1. Service-to-Service Runtime Calls: Secured with high-entropy Application API Keys (Authorization: Bearer sendrin_<prefix>.<secret>).
2. Management & Console Calls: Secured with OpenID Connect JWT tokens issued by IITD Central IAM (https://auth.iitdeveloper.com).

1. Application API Keys (Runtime Dispatch)

Every transactional request (/api/v1/notifications, /api/v1/otp/send, /api/v1/otp/verify) must include an Authorization header containing an active application key:

Authorization: Bearer sendrin_a1b2c3d4e5f6.xY7z...

Key Formats & Prefixes

Application keys are formatted as sendrin_<prefix>.<secret>:

• Prefix (<prefix>): An alphanumeric identifier of at most 12 characters stored alongside the key hash for quick indexed lookups.
• Secret (<secret>): A cryptographically random secret hashed with scrypt (N=16384, r=8, p=1, dklen=32) using a per-key salt and server pepper. The plaintext secret is revealed only once at creation time.

[!CAUTION] Treat application keys like passwords. Never expose them in client-side mobile apps or single-page web applications without a backend proxy.

2. Central IAM SSO Tokens (Management & Console)

When accessing workspace settings, adding custom domains, or adjusting commercial billing plans, endpoints authenticate via JSON Web Tokens (JWT) issued by Keycloak under the iitdeveloper realm:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

The JWT token contains tenant claims (tenant_id, sub, roles) verified against IITD Central IAM's public JWKS endpoint (https://auth.iitdeveloper.com/realms/iitdeveloper/protocol/openid-connect/certs).

3. RBAC Scopes & Permissions

GNS enforces granular permission scopes across all operations:

4. Error Responses

If an invalid or expired credential is supplied, Sendrin returns a standardized JSON error:

{
  "code": "invalid_credential",
  "message": "Credential is invalid or expired"
}