Constructive Principals

Constructive Principals

Principals are scoped sub-identities of a human user. They are how you give an agent or an API key its own identity that acts on a human's behalf while carrying only a subset of that human's capabilities. A principal never exceeds its owner's access, and everything it does still meters and audits back to the owning human.

This skill covers principals from the application layer — how to create them, hand them short-lived tokens, delegate narrower children, issue and revoke standing API keys, scope them to specific orgs, and gate their capabilities behind earned trust, all through the generated SDK ORM. It intentionally does not cover the SQL/trigger internals (see the constructive-db-principals skill in constructive-db for that).

The App access and Organizations feature packs provide host-facing principal and API-key management views when the tenant exposes compatible operations. Use constructive-blocks for those UI surfaces; use this skill for the identity and authority model.

When to Apply

Use this skill when:

• Giving an AI agent a credential for a run — a short-lived access token with a rotating refresh token (mintAccessToken / refreshAccessToken)
• Letting an agent hand a sub-task to a strictly narrower child principal (createChildPrincipal)
• Creating a principal from a preset (read-only-analyst, deploy-bot) in one call
• Issuing a standing API key for a CI pipeline, script, webhook, or integration — and understanding the TTL caps that clamp it
• Creating a read-only credential that physically cannot write
• Scoping a credential to specific orgs (or leaving it unrestricted)
• Revoking a session, key, or principal and understanding what cascades
• Withholding capabilities from an agent until it has earned trust (agent ladder, unlocks, revoked_by) and reading the refusals it hit (error-code events, limit_refusals)
• Understanding why a credential can see less than its owning human

Principal vs Agent vs API Key

All principals are the same underlying identity (a user with type = 3). The distinction is how you use them:

So: "create an API key", "mint an access token" and "create an agent credential" all attach a credential to a principal. See constructive-agents for the AI/persona side.

Core Model (application view)

• A principal is owned by a human (ownerId) and has its own identity user row (userId, type = 3).

• Its capabilities are parent_capabilities & allowedMask — capabilities can only shrink, never exceed the owner's. allowedMask = null means "inherit all of the owner's capabilities".

• When the owner gains/loses access (e.g. removed from an org), the principal's access follows automatically.

• Identity vs authority: billing, rate limits, ownership, and created_by/updated_by always meter to the human; only capability checks use the principal's own precomputed capabilities. For a normal (non-principal) session the two are identical — zero behavioral change.

• Trust can only withhold. A scope's trust ladder may name unlocks a principal does not get until it earns a level; it can never add bits the owner lacks. Effective authority is authority & allowedMask & ~(locked & ~unlocked).

Principal management is human-only (AuthzHumanOnly): a principal cannot create, widen, or issue standing keys for principals — PRINCIPAL_CANNOT_CREATE_PRINCIPAL. The one carve-out is createChildPrincipal: a principal may mint a strictly narrower child of itself, and mintAccessToken for a principal it already is. Anything wider fails with PRINCIPAL_CHILD_WIDENS.

ORM Quick Reference

The generated auth ORM client (db) exposes principals as tables plus a set of custom mutations.

Tables (CRUD: findMany / findOne / create / update / delete)

RLS: you only ever see principals you own (AuthzDirectOwner on ownerId).

Custom mutations

Plaintext credentials are returned exactly once. apiKey, accessToken and refreshToken are never retrievable again — store them immediately. Afterwards only metadata (keyId, name, expiresAt, lastUsedAt, revokedAt) is queryable.

Custom mutations take two arguments: the variables { input }, then an options object with a select.

Give an agent a short-lived credential (recommended)

// From a human (or standing-key) session, for a principal you own
const { mintAccessToken } = await db.mutation
  .mintAccessToken(
    { input: { principalId: '<principal-user-uuid>', intent: 'nightly-report', accessTtl: { minutes: 10 } } },
    { select: { result: { accessToken: true, refreshToken: true, sessionId: true, accessExpiresAt: true } } },
  )
  .execute()
  .unwrap();

// Later, before accessExpiresAt: rotate (the old refresh token dies)
const { refreshAccessToken } = await db.mutation
  .refreshAccessToken(
    { input: { token: mintAccessToken.result.refreshToken } },
    { select: { result: { accessToken: true, refreshToken: true, accessExpiresAt: true } } },
  )
  .execute()
  .unwrap();

Access TTL is capped by the tenant (auth_settings.access_token_duration, default 15 min); refresh defaults to 30 days and the chain never outlives max_session_chain_age (90 days). Presenting a spent refresh token revokes the whole session tree and fails with REFRESH_TOKEN_REUSED. Full rules, claims (jwt.claims.intent, lineage) and revocation cascades: access-tokens.md.

Delegate a narrower child

const { createChildPrincipal } = await db.mutation
  .createChildPrincipal(
    {
      input: {
        parentPrincipalId: '<parent-principal-user-uuid>',
        name: 'deploy-job-4821',
        entityIds: ['<org-uuid>'],              // ⊆ parent's entities
        expiresAt: '2026-09-06T00:00:00Z',      // ≤ parent / chain expiry
        isReadOnly: true,
      },
    },
    { select: { result: true } },
  )
  .execute()
  .unwrap();
// then mintAccessToken({ principalId: createChildPrincipal.result, ... })

A child can only be narrower: a wider allowedMask, an entity outside the parent's list, or a later expiry fails (PRINCIPAL_CHILD_WIDENS, PRINCIPAL_CHILD_TTL_EXCEEDS_PARENT). See delegation.md.

Create a principal from a preset

const { createPrincipalFromPreset } = await db.mutation
  .createPrincipalFromPreset(
    { input: { slug: 'deploy-bot', name: 'release-bot', entityIds: ['<org-uuid>'] } },
    { select: { result: true } },
  )
  .execute()
  .unwrap();

Shipped slugs: read-only-analyst (all of the owner's bits, read-only, no delegation) and deploy-bot (manage_services / manage_sites / manage_domains at org scope, entity list required, one level of delegation). overrides may only tighten. See delegation.md.

Create a standing API key (owner-scoped)

const { createApiKey } = await db.mutation
  .createApiKey(
    {
      input: {
        keyName: 'ci-deploy',
        accessLevel: 'full_access',    // or 'read_only'
        mfaLevel: 'none',
        expiresIn: { days: 90 },       // IntervalInput; clamped to the strictest tenant/principal/org cap
      },
    },
    { select: { result: { apiKey: true, keyId: true, expiresAt: true } } },
  )
  .execute()
  .unwrap();

// createApiKey.result.apiKey — show/store now; you cannot read it again.

Create a read-only key

Set accessLevel: 'read_only'. The credential runs every request in a PostgreSQL read-only transaction — it physically cannot write, regardless of the owner's capabilities. See constructive-security → read-only-access.md.

Scope an agent/key to a specific org

// 1. Create an org-scoped principal (caller must be an admin of orgId)
const { createOrgPrincipal } = await db.mutation
  .createOrgPrincipal(
    {
      input: {
        name: 'reporting-bot',
        orgId: '<org-uuid>',
        isReadOnly: true,
        bypassStepUp: true,   // principals can't do MFA; true skips step-up
      },
    },
    { select: { result: true } },
  )
  .execute()
  .unwrap();

const principalId = createOrgPrincipal.result; // new principal id

// 2. Mint a key for it
const { createOrgApiKey } = await db.mutation
  .createOrgApiKey(
    {
      input: { orgId: '<org-uuid>', principalId, keyName: 'reporting-bot', accessLevel: 'read_only' },
    },
    { select: { result: { apiKey: true, keyId: true } } },
  )
  .execute()
  .unwrap();

Org scoping via absence: a principal with no principalEntity rows inherits access to all orgs its owner belongs to. Adding rows restricts it to only those orgs. See org-scoping.md.

Scoping to non-org entity types: the same principalEntity mechanism covers rows of any provisioned entity type, and some deployments instead take entityIds at principal creation. Probe first — org-scoping.md has the check and both surfaces.

Entity-scoped keys, end to end

entity-scoped-keys.md is the ordering recipe for the cross-plane flow (entity type → scoped principal → step-up → mint → use/revoke) and the three constraints that fix that order: keys are personal at mint, scope may be fixed at principal creation, and step-up is per session. For org-only scoping, prefer the createOrgPrincipal flow above.

Revoke

await db.mutation
  .revokeApiKey({ input: { keyId: '<key-uuid>' } }, { select: { result: true } })
  .execute()
  .unwrap();

Revoking disables the credential but keeps the row (with revokedAt set) for audit, and revokes every session and token that was exchanged from the key. revokeSession({ sessionId }) does the same for a minted token pair and its descendants. Deleting a principal cascades — its children, keys, org scoping, and identity row all go, while created_by/updated_by on data it touched still point to the human (no orphans).

Trust & Refusals

A scope's trust ladder can withhold capabilities from principals until they earn a level. The shipped agent preset (["events_module", { "scope": "org", "trust_ladder": "agent" }]) grants agent_proven after 3 and agent_trusted after 10 agent.run.completed events in 30 days; agent_trusted lapses after 30 days and is revoked (with progress reset) by token.refresh_reused or PRINCIPAL_CHILD_WIDENS. Which bits are withheld is yours to name via unlocks — the preset ships none.

Refused mutations are recorded by ErrorEventsPlugin after rollback as events whose name is the error code itself (PRINCIPAL_CHILD_WIDENS, LIMIT_REACHED, … with payload.operation) — nothing prefixed, so revoked_by is one flat list of event names — and the quota family is exposed through the tenant's limit_refusals view. See trust-and-refusals.md.

References

Cross-References

• Identity & sessions: constructive-auth — how humans authenticate; principals authenticate via API keys instead of passwords/magic links.
• Capabilities: constructive-access-control — the capability model whose subset a principal carries (allowedMask).
• Enforcement: constructive-security — AuthzHumanOnly (blocks principals from managing principals), read-only access, RLS.
• Trust ladders & events: constructive-events — humanity / metered ladders, base rung fields, EventTracker; the agent ladder and unlocks are covered here.
• Auth settings: constructive-auth → auth-settings.md — where the tenant-level token/delegation ceilings (auth_settings.*) are edited.
• Agents: constructive-agents — attaching an agent_module (persona, threads) to a principal.
• Entity types: constructive-entities — the multi-tenancy model behind the entity rows that scoped principals are limited to.
• Planes: constructive-architecture — control plane vs data plane: entity types provision with the platform token; principals and keys mint with the per-database token.
• App access and Organizations UI: constructive-blocks — standalone host contracts plus Console module discovery and adapters.
• SQL internals: constructive-db-principals skill (in constructive-db) — dual-claim JWT, principal_auth_module, SPRT sync triggers. Not needed for app development.