API keys

API keys authenticate requests to NamoID. Auth keys are scoped to one environment. Platform keys are scoped to the tenant and are meant for server-side automation across projects and environments.

Using AI to configure NamoID? Give the AI agent a platform key, not an auth key. Platform keys are the tenant-level credential for trusted setup agents, CLIs, CI jobs, and agency automation.

Three key types

Type	Prefix	Scope	Use
Auth publishable	`namoid_auth_pk_{test,live}_…`	environment	browser-safe; fetch auth config from the frontend
Auth secret	`namoid_auth_sk_{test,live}_…`	environment	server-side auth/session/token operations
Platform secret	`namoid_platform_sk_…`	tenant	server-side automation across projects and environments

Auth keys encode their environment (test/live) in the prefix; platform keys are environment-independent (the target project/environment is passed in the route or body). The plaintext key is shown exactly once at creation — after that only its hash is stored, so copy it immediately.

Authenticate a request

curl https://api.namoid.in/v1/api-keys/whoami \
  -H "X-API-Key: $NAMOID_PLATFORM_KEY"

Auth publishable config

Use the auth publishable key from your frontend to fetch browser-safe auth configuration. The request must come from one of the key's allowed origins.

curl https://api.namoid.in/v1/auth/config \
  -H "X-API-Key: $NAMOID_AUTH_PUBLISHABLE_KEY" \
  -H "Origin: https://app.example.com"

Auth secret token validation

Use the auth secret key from your backend to validate NamoID access tokens.

curl https://api.namoid.in/v1/auth/tokens/validate \
  -H "X-API-Key: $NAMOID_AUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJ..." }'

Platform environment settings

Use the platform secret key from trusted backend automation to read or update settings for an environment owned by the same tenant.

curl https://api.namoid.in/v1/platform/projects/$PROJECT_ID/environments/$ENVIRONMENT_ID/settings \
  -H "X-API-Key: $NAMOID_PLATFORM_KEY"

Access controls

A key can be constrained so a leaked credential is far less useful:

Allowed origins — publishable keys must declare the web origins they may be called from; the runtime rejects mismatched Origin headers.
IP allowlist — restrict a key to specific source IPs.
Rate limits — per-key request limits, enforced in Redis. Exceeding them returns 429.
last_used_at — each key records when it was last used, for audit and stale-key cleanup.

Rotation

From the dashboard, the rotate action issues a new key and disables the old one immediately. There is no grace window, so schedule your rollouts to restart all callers before you click Rotate.

Auth publishable keys

If you issue an auth publishable key, you must declare allowed origins at creation. The runtime rejects calls whose Origin header does not match. That protects the key from being lifted from one website and reused on another.

Secret keys

Auth secret and platform secret keys are server-side credentials. Never expose them in browser code, mobile apps, public repositories, client logs, or support screenshots.

Platform keys

Platform keys (namoid_platform_sk_…) are tenant-level credentials — the key type for trusted server-side automation: setup scripts, CLIs, agency automation, CI, and AI agents that configure NamoID on behalf of a tenant. Unlike auth keys, they are not tied to one project or to test/live; the target project and environment are supplied in the route or body, so a single platform key can manage every project in the tenant.

What a platform key can do

Authenticate as the tenant for management and automation calls.
Create, read, and update tenant projects and environments.
Manage environment applications, API/resource servers, provider settings, webhooks, auth keys, and environment settings for any project in the tenant.
Be created, listed, rotated, and revoked by tenant admins only.
Platform keys are customer-tenant automation keys. The NamoID Root Tenant does not expose platform keys through the public management API.

Because a platform key is powerful and tenant-wide, treat it like a high-privilege secret: store it in a secret manager, never in client code or a repo, and rotate it on a schedule.

Platform key scopes

Platform keys also carry scopes. Use * only for fully trusted internal automation. For narrower AI/CLI setup agents, issue the smallest scope needed:

Scope	Allows
`projects:read` / `projects:write`	List, fetch, create, or update tenant projects
`environments:read` / `environments:write`	List, fetch, create, or update project environments
`env.settings:read`	Read environment settings
`env.settings:write`	Update environment settings
`applications:read` / `applications:write`	Manage OAuth/OIDC applications and rotate client secrets
`resource_servers:read` / `resource_servers:write`	Manage API/resource server audiences and scopes
`providers:read` / `providers:write`	Manage external/social provider configuration
`webhooks:read` / `webhooks:write`	Manage webhook subscriptions
`auth_keys:read` / `auth_keys:write`	Manage publishable and backend auth keys
`users:read`	Read environment user data once platform-key user endpoints are enabled
`*`	All platform-key operations currently available to that tenant

Authenticating

Send the key in either header form:

# Preferred
curl https://api.namoid.in/v1/api-keys/whoami \
  -H "X-API-Key: $NAMOID_PLATFORM_KEY"

# Also accepted
curl https://api.namoid.in/v1/api-keys/whoami \
  -H "Authorization: ApiKey $NAMOID_PLATFORM_KEY"

/v1/api-keys/whoami confirms the key resolves and shows what it's scoped to — handy as a smoke test in automation.

Managing platform keys

Admin-only, scoped to the tenant. The plaintext is returned once on create and rotate.

Method	Path	Purpose
GET	`/v1/tenants/{tenant_id}/platform-keys`	List the tenant's platform keys
POST	`/v1/tenants/{tenant_id}/platform-keys`	Create one (plaintext returned once)
GET	`/v1/tenants/{tenant_id}/platform-keys/{key_id}`	Fetch one key's metadata
PATCH	`/v1/tenants/{tenant_id}/platform-keys/{key_id}`	Update a key (e.g. label, IP allowlist)
POST	`/v1/tenants/{tenant_id}/platform-keys/{key_id}/rotate`	Issue new plaintext; old invalidated
DELETE	`/v1/tenants/{tenant_id}/platform-keys/{key_id}`	Revoke — effective immediately

Using a platform key

Manage any tenant project/environment without a user session:

# Create a project
curl -X POST https://api.namoid.in/v1/platform/projects \
  -H "X-API-Key: $NAMOID_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"acme-app","name":"Acme App"}'

# Read environment settings
curl https://api.namoid.in/v1/platform/projects/$PROJECT_ID/environments/$ENV_ID/settings \
  -H "X-API-Key: $NAMOID_PLATFORM_KEY"

# Update environment settings
curl -X PATCH https://api.namoid.in/v1/platform/projects/$PROJECT_ID/environments/$ENV_ID/settings \
  -H "X-API-Key: $NAMOID_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "...": "..." }'

# Create an OAuth/OIDC application in an environment
curl -X POST https://api.namoid.in/v1/platform/projects/$PROJECT_ID/environments/$ENV_ID/applications \
  -H "X-API-Key: $NAMOID_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Web app","application_type":"web","redirect_uris":["https://app.example.com/callback"]}'

Platform vs. auth keys at a glance

	Auth keys	Platform keys
Scope	One project environment	Whole tenant
Prefix	`namoid_auth_pk_…` / `namoid_auth_sk_…`	`namoid_platform_sk_…`
Env in prefix	Yes (`test` / `live`)	No (env passed in route/body)
Typical use	Frontend config; backend token/session ops	Cross-project and cross-environment automation
Who manages	Tenant members with project access	Tenant admins only