Security

Authentication, authorization, and security architecture for GoTamil API.

Authentication Overview

GoTamil API implements defense-in-depth authentication with four distinct mechanisms for different access patterns.

Layer	Mechanism	Endpoints
User API	OIDC Bearer tokens	`/v1/proofread`, `/v1/essay-critique`, `/v1/operations`
Admin API	OIDC with role verification	`/v1/admin/*`
Operator API	Identity verification	`/v1/operator/`, `/v1/internal/`
Worker	Internal task auth (token/OIDC)	`/internal/tasks/*`
Admin Console	Supabase OAuth (Google Sign-In)	Console UI

Role-Based Access Control

Five roles govern access across the platform:

Role	Scope	Access Level
`tenant_admin`	Tenant	Full management — BYOK, certification, onboarding, dashboard
`tenant_viewer`	Tenant	Read-only — onboarding status, dashboard
`service_integration`	Tenant	Service account access for AI endpoints
`gotamil_operator`	Platform	Operator — invites, tenants, admin members
`unknown`	—	Denied

Roles are extracted from JWT claims. The API checks multiple claim paths: gotamil_roles, roles, role, app_metadata.gotamil_roles, app_metadata.roles.

Tenant Isolation

Every API request is scoped to the tenant_id from the JWT
Operations can only be polled by the tenant that created them
Row Level Security (RLS) is enabled on all tenant data tables
Supabase anon and authenticated privileges are revoked on API tables

Secrets Management

All sensitive values are stored in Google Cloud Secret Manager:

Secret	Purpose
Database URL	PostgreSQL connection string
OIDC JWKS	Public key set for token validation
BYOK credentials	Per-tenant Gemini API keys
Invite token secret	HMAC signing key for invites
Internal task token	Worker authentication

Idempotency

Critical mutation endpoints support idempotent requests via the Idempotency-Key header:

Scope: unique per (tenant_id, endpoint, idempotency_key)
Reservation TTL: 120 seconds for in-progress requests
Conflict: 409 if same key is being processed by a different request

Audit Trail

Every significant mutation is recorded in the tenant_audit_events table with:

Event type and result
Actor subject (user or system ID)
Request ID and operation ID
Actor email and roles
Timestamp

See Audit Logging in the feature spec for the complete event type list.

Production Safety Guards

The API validates critical security configuration at startup:

Dev tokens are blocked in production
JWKS key set is required
Internal task tokens must not use default values
Invite secrets must meet minimum length
Console URL must use HTTPS
Internal task auth must use OIDC (not shared token)