Authentication

GoTamil API uses OIDC bearer tokens for user-facing endpoints and role-based access control to gate admin and operator operations.

Auth Mechanisms

Mechanism	Used For	Source
OIDC Bearer	User endpoints (proofread, essay-critique, admin)	`Authorization: Bearer <jwt>`
Identity Verifier	Operator/internal endpoints	`Authorization: Bearer <jwt>`
Internal Task Auth	Cloud Tasks worker	`X-Internal-Task-Token` (dev) or Google OIDC (prod)
Supabase OAuth	Admin console sessions	Google Sign-In via Supabase

Your JWT must include these claims:

Claim	Description
`iss`	Must match configured issuer (default: `https://nimir.internal`)
`aud`	Must match configured audience (default: `gotamil-api`)
`tenant_id`	Your tenant identifier (claim path is configurable)

Role claims are extracted from multiple possible paths: gotamil_roles, roles, role, app_metadata.gotamil_roles, or app_metadata.roles.

Role	Access
`tenant_admin`	Full tenant management — BYOK, certification, onboarding, dashboard
`tenant_viewer`	Read-only — onboarding status, dashboard feed
`service_integration`	Service account access for API endpoints
`gotamil_operator`	Platform operator — invites, tenants, admin members

Endpoint Group	Required Role
`/v1/proofread`, `/v1/essay-critique`	Any authenticated user with valid `tenant_id`
`/v1/operations/:id`	Any authenticated user (must match tenant)
`/v1/admin/onboarding/`, `/v1/admin/dashboard/`	`tenant_admin` or `tenant_viewer`
`/v1/admin/byok/`, `/v1/admin/integrations/`	`tenant_admin`
`/v1/operator/*`	`gotamil_operator`
`/v1/internal/*`	`gotamil_operator`

Production deployments enforce: