Identity (OIDC)

The fleet identity provider — one OIDC issuer for all products, so a single account authenticates across the fleet (the cross-product SSO the census found impossible). Signs RS256/JWKS; per-brand realms. Consolidates the 19-service platform auth + voice + bellring (C3). The signing key is resolved server-side and NEVER present in a repo, a consumer, or a facade. Status: OIDC provider LIVE (discovery+JWKS+authorize+token+userinfo+introspect+revoke+register+ session/end served by node-oidc-provider) + strong-auth surface (MFA/WebAuthn/lockout/enterprise-SSO) ABSORBED from vagary-platform (Track S core-merge, additive). Consolidation remains the staged C3 build: Phase 1 ETL → G0 gate → Phase 2 repoint-with-fallback → Phase 3 per-consumer deletes (voice last).

• Group: Auth & gateway
• Contract: contracts/identity/v1/openapi.yaml
• Public access: none — internal-only capability. It is NOT exposed on the public API gateway (https://api.vagarylabs.com); it is reachable only inside the fleet (container/tailnet) by first-party callers. There is no customer-facing endpoint to call.

Endpoints

Method	Path	Summary
GET	/.well-known/openid-configuration	OIDC discovery document (GROUNDED — live in scaffold)
GET	/jwks	JSON Web Key Set — public keys for RS256 verification (GROUNDED — live in scaffold)
POST	/token	OAuth2/OIDC token endpoint (GROUNDED — real grant handling via node-oidc-provider)
GET	/health	liveness
GET	/metrics	Prometheus text exposition
POST	/provision/users	Provision a product end-user (internal signup delegation — identity is the SOLE cred store)
POST	/provision/password	Change a product end-user's password (internal delegation)
POST	/password-reset/request	Begin a self-service password reset
POST	/password-reset/confirm	Redeem a reset token and set a new password
POST	/provision/erase-subject	GDPR Art-17 SUBJECT-scoped erasure — forget a person across all 25 identity tables
GET	/authorize	OAuth2/OIDC authorization endpoint (authorization_code + PKCE) — GROUNDED
GET	/userinfo	OIDC UserInfo (bearer access token) — GROUNDED
POST	/introspect	RFC 7662 token introspection (client-authenticated) — GROUNDED
POST	/revoke	RFC 7009 token revocation (client-authenticated) — GROUNDED
POST	/register	OIDC dynamic client registration — GROUNDED
GET	/session/end	OIDC RP-initiated logout (end_session) — GROUNDED
POST	/account/mfa/enable	begin TOTP MFA enrollment (returns secret + backup codes ONCE)
POST	/account/mfa/activate	verify the first TOTP code and activate MFA
POST	/account/mfa/verify	verify a TOTP or a one-time backup code
POST	/account/mfa/disable	disable MFA for a user
GET	/account/mfa/status	MFA status for a user
POST	/account/webauthn/register-begin	begin WebAuthn passkey registration (issue challenge)
POST	/account/webauthn/register-complete	complete WebAuthn passkey registration
POST	/account/webauthn/authenticate-begin	begin WebAuthn assertion (issue challenge)
POST	/account/webauthn/authenticate-complete	complete WebAuthn assertion (sign-count anti-clone enforced)
GET	/account/webauthn/credentials	list a user's registered passkeys
POST	/account/webauthn/credentials-remove	remove a user's passkey
POST	/account/sso/providers	register an upstream SSO provider (saml
GET	/account/sso/providers	list registered SSO providers
POST	/account/sso/initiate	initiate SSO login (SAML redirect / OIDC authorization URL)
POST	/account/sso/callback	handle an SSO callback (SAML response / OIDC code)
POST	/account/sso/link	link an upstream SSO identity to a local user
GET	/account/sso/links	list a user's SSO links
POST	/account/sso/unlink	remove an SSO link
POST	/account/sessions/create	create a tracked device session
GET	/account/sessions	list a user's active sessions
POST	/account/sessions/revoke	revoke a single session
POST	/account/sessions/revoke-all	revoke all sessions (optionally all-except keep_session_id)
POST	/account/security/revoke-user-tokens	blanket-revoke ALL of a user's tokens (logout-all / compromised account)
POST	/account/security/revoke-jti	deny a specific token by its jti for a ttl
GET	/account/security/token-status	check per-user blanket + per-jti revocation status (for consumers enforcing revocation)
GET	/account/security/revocations	incremental revocation delta since a monotonic cursor (JTI denylist + user-blanket entries)
POST	/account/social/authorize	build a social-provider authorization URL (+ CSRF state carrying realm/org context)
POST	/account/social/callback	handle a social callback (code-exchange, profile fetch, find-or-create + link)
GET	/account/social/links	list a user's linked social providers
POST	/account/social/unlink	unlink a social provider from a user
POST	/account/api-keys	issue an org-scoped api-key for a user (returns the raw key ONCE)
GET	/account/api-keys	list an org's api-keys (redacted — no hash); optional user_id narrows to one user
POST	/account/api-keys/verify	verify a raw api-key (raw key in the body — never a URL); returns org/user/scope context
PATCH	/account/api-keys/{keyId}	update an org's api-key name and/or scopes (folds platform update_key)
DELETE	/account/api-keys/{keyId}	revoke an org's api-key by its external handle

Schemas

Jwks

Field	Type	Description
keys	array

ProvisionUserRequest

Field	Type	Description
realm	string	per-brand realm the user belongs to
email	string
password	string
organization_id	string	product-tier end-customer tenant (I6 — never Paperclip companyId)
name	['string', 'null']
roles	array

ProvisionedUser

Field	Type	Description
id	string
email	string
realm	string
organization_id	string

PasswordResetRequest

Field	Type	Description
realm	string
email	string

PasswordResetConfirm

Field	Type	Description
token	string	the raw reset token from the emailed link; never logged or stored
password	string	the new password

Accepted

Field	Type	Description
status	string

ProvisionPasswordRequest

Field	Type	Description
realm	string
id	string	subject (user id / sub)
password	string

PasswordUpdated

Field	Type	Description
updated	boolean

---

Generated by scripts/gen-capability-docs.py from contracts/identity/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.