Authentication & Security

GNS implements two authentication tiers depending on the operation:

1. Service-to-Service Runtime Calls: Secured with high-entropy Application API Keys (Authorization: Bearer gns_live_sk_...).
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 gns_live_sk_9d8f7e6a5b4c3d2e1f0a

Key Formats & Prefixes

• Live Production Keys: gns_live_sk_<40_char_hex>
• Test / Sandbox Keys: gns_test_sk_<40_char_hex>

[!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, GNS returns a standardized JSON error:

{
  "error": "invalid_credential",
  "message": "The provided Bearer token is invalid or has been revoked.",
  "code": "GNS_AUTH_001"
}