Entities

iam.svc ships an embedded base schema — one definition per entity, materialized per tenant. Products layer additional entities or fields via iam/extend/ (see Configuration).

Identity

Entity	Purpose
`users`	Principals. `id` is a ULID prefixed `U`; `email` and `mobile` are marked for auth/identity use; `password` is argon2id-hashed; roles live in `properties.roles`; `allow_impersonation` (default `false`) gates operator impersonation. Row-level security narrows non-admin reads to the caller’s own row; changes are audited
`iamagents`	Autonomous agents (`A` prefix) — realm feature toggle
`iambots`	Bots (`B` prefix) — realm feature toggle
`delegation`	Delegates acting for another user (`D` prefix) — realm feature toggle
`userattribute`	Custom per-user attributes
`tracked_anonymous_user`	Pre-login anonymous identities (fed by the gateway tracker)

ID prefixes: U user · A agent · B bot · D delegate.

Authentication state

Entity	Purpose
`session`	Managed sessions: opaque `session_id` (≥128-bit, unique-indexed), principal, CPET, status (`active/revoked/expired`), AAL, auth method, IdP issuer/session pair (for back-channel logout), idle/absolute timing, revocation reason, impersonator fields. All CRUD restricted to the service principal
`api_key`	Issued API keys — the secret is returned once at issue time, stored hashed
`user_refresh_token`	Rotating refresh-token families, hashed
`user_token`, `user_otp`, `user_mfa_request`	Short-lived flow state (MFA, OTP)
`user_magic_link`	Magic-link codes
`user_lock`	Lockout state
`password_reset_request`	Reset codes
`oauthstate`	OAuth PKCE state (10-minute lifetime)
`webauthn_session`, `webauthn_credential`	WebAuthn ceremonies + registered credentials
`federation_request`	Federation handshakes

Authorization and tenancy

Entity	Purpose
`role`	Role definitions
`realm`	Which entity authenticates, with which providers (see Authentication)
`group`	User groups
`tenant`	The tenant registry (control plane)
`tenant_extensions`	Tenant-layer config overlays, stored as rows (path + YAML body)
`superadmin`	Control-plane operators (in the superadmin plane only)
`superadmin_grant`	Which tenants an operator may manage — enforced by row-level security
`jwt_signing_key`	Per-tenant generated signing keys (only when no vault/inline key is configured)

Audit

Entity	Purpose
`user_eventlog`	Per-user auth events
`tenant_eventlog`	Tenant-level events

Extending the schema

Two overlay forms in iam/extend/*.yaml:

New entity — a full entity definition; it becomes a table and appears at /rest/<name>.
Augment — augments: users adds fields to a base entity.

Tenant-layer extensions (rows in tenant_extensions) merge on top of the product layer and are augment-only: they may add, never shadow. Shadowing a base field fails the engine build for that tenant — loudly, at boot or refresh, not at request time.

Access to every entity is governed by the entity’s access: rules (JS/expr predicates receiving the caller’s claims), plus row-level security where declared. The auth flows themselves run under an internal service principal that satisfies engine rules but grants callers nothing.