Authentication

Unveilr uses one Admin API origin and three credential types. Pick the credential that matches the caller — never share agent tokens with CI, and never send client-selected tenant headers.

Base URL

export UNVEILR_API=https://guard.unveilr.ai

Self-hosted: use your CloudFront / operator URL. See Production APIs and Self-hosting.

All authenticated Admin calls:

Authorization: Bearer <credential>

Credential types

Caller	Credential	How you get it
Human (console)	WorkOS OIDC JWT	SSO into /o/<org-slug>
CLI / CI / automation	Service token uvt_…	Settings → API Tokens, or POST /v1/tokens
Agent runtime (enterprise)	IdP JWT (Okta / Entra / OIDC)	Settings → Identity Providers → bind subject via Approve external
Agent runtime (lab)	Agent token uvt_…	Register agent → Approve (shown once)

Service tokens

Minted by a tenant admin. The full secret is returned once at creation.

curl -fsS -X POST "$UNVEILR_API/v1/tokens" \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "content-type: application/json" \
  -d '{"name":"github-actions","scopes":["scan:upload"],"expiresInDays":90}'

export UNVEILR_TOKEN=uvt_…
curl -fsS "$UNVEILR_API/v1/onboarding" \
  -H "Authorization: Bearer $UNVEILR_TOKEN"

List and revoke (prefix only — secret never reappears):

curl -fsS "$UNVEILR_API/v1/tokens" -H "Authorization: Bearer $ADMIN_JWT"
curl -fsS -X DELETE "$UNVEILR_API/v1/tokens/{tokenId}" \
  -H "Authorization: Bearer $ADMIN_JWT"

CLI login

unveilr login --token "$UNVEILR_TOKEN" --api "$UNVEILR_API"

Agent credentials (enterprise IdP — preferred)

1. Configure Okta / Entra / OIDC under Settings → Identity Providers (use Discover to fill JWKS from the well-known document).
2. Register the agent → Bind IdP & approve with the IdP subject (sub / oid / custom claim).
3. The agent presents its IdP-issued JWT to the Gateway or POST /v1/govern/check. No Unveilr secret is minted.

Full runbook: Enterprise agent identity.

Agent tokens (lab / no IdP)

1. Console → Agents → register (name + owner email + allowed tools).
2. A second admin approves in production (separation of duties).
3. Copy the uvt_… token (once).
4. Call Gateway /mcp/… or POST /v1/govern/check.

See Govern check and Govern.

Scopes

Scope	Typical use
scan:upload	Default CI / CLI upload token
agent:invoke	Bound to an approved agent identity
agent:<name>	Per-agent binding label
mcp:admin / mcp:call	MCP client access paths

Least privilege: CI tokens should be scan:upload only. Agent tokens are runtime-only — do not put them in GitHub Actions secrets meant for scanning.

Roles (SSO)

Role	Capability
Org member	Console triage, findings, evidence (as permitted)
Tenant admin	Tokens, GitHub, agents, org SSO/SCIM, policies
super_admin / platform_admin	Cross-tenant provisioning (/v1/platform/*)

Role claims come from signed WorkOS tokens, not client-supplied headers.

What never works in production

Anti-pattern	Why
X-Unveilr-Tenant / X-Unveilr-User / X-Unveilr-Roles	Automated-test seam; rejected by supported runtimes
Calling /internal/*	Gateway/control-plane only — not a customer API
Reusing a revoked or expired uvt_	Fail closed → 401
Using an unapproved agent credential	Fail closed → 403

Health (no auth)

curl -fsS "$UNVEILR_API/healthz"
curl -fsS "$UNVEILR_API/readyz"   # fails if the database is down

Next

• Persona playbooks — first success for every caller
• API conventions — errors, pagination, limits
• Endpoint reference — /v1 catalog