The Entity Model
The directory is built on a small, deliberate set of crypto-bearing principal kinds. A principal is something that can hold keys, authenticate, be authorized, and be held accountable. Everything else, groups, roles, policies, is modeled separately, precisely so the set of principals stays small and every member of it carries a real cryptographic identity.
Six crypto-bearing principals share one foundation, one identity path, one authorization path, one crypto identity. There is no organizational-unit entity, agents and users are peers, and every entity gets one workspace automatically.
The model at a glance
Figure A2: the entity & identity model. The six principals (green foundation, plain boxes) all sit on one identity/authorization/crypto foundation; the governance records (amber) live in their own tables and never become entities; every entity is auto-provisioned one workspace (cyan). The detached, dashed box records what is deliberately absent: there is no organizational-unit entity.
Table equivalent
| Element | Kind | Crypto-bearing principal? | Relationship |
|---|---|---|---|
| Organization | Principal | Yes | Trust root; holds the certificate authority; on the one foundation |
| User | Principal | Yes | A person; peer of Agent: same lookup, grant, audit, and billing machinery |
| Agent | Principal | Yes | An AI agent delegated by a responsible user; peer of User |
| Service account | Principal | Yes | Non-human automation |
| Node | Principal | Yes | Infrastructure system identity |
| Device | Principal | Yes | An edge or IoT endpoint |
| Group | Governance record | No | Organizes principals; its own table; never keyed as an entity |
| Role | Governance record | No | An assignment attached to a principal within a scope |
| Policy | Governance record | No | Belongs to the scope vocabulary (org, cell, service group, node, workspace) |
| Domain | Governance record | No | A governance domain; its own table |
| Default workspace | Auto-provisioned resource | n/a | Created automatically, one per entity, at provisioning time |
| Organizational unit | (deliberately absent) | No | Not an entity: exists only as an X.509 subject field on an issued certificate |
The principal kinds
A single enum is the source of truth for the principal kinds, and a guard invariant keeps anything that is not a key-holding principal out of it:
| Principal | What it is |
|---|---|
| User | A human. The base identity for a person. |
| Service account | A non-human automation principal. |
| Agent | An AI agent, always linked to a responsible user by delegation. |
| Node | An infrastructure host or instance; its identity survives cell replacement. |
| Device | A hardware device: an edge or IoT endpoint. |
| Organization | The org itself; the trust root, seeded first, holding a certificate authority. |
The model is deliberately extensible: because a principal is defined by data (an entity-types table and per-format crypto policy) rather than by branching code, a future principal kind that holds keys and owns resources is added by declaration rather than by rewriting every crypto manager and policy adapter.
One creation pipeline
All principals are created through a single identity manager and one
persona-creation pipeline, create_user, create_node, create_device,
create_agent, create_service_account, create_organization, with
kind-validated profile fields. There is no separate machine-identity system and
no separate agent registry. Immediately after a principal's directory row is
created, an orchestrator issues its X.509, SSH, and OpenPGP material (see
Authentication).
A human user's base identity can carry more than one persona lens, for example a personal lens and a professional lens, each with its own crypto material and default profile, while sharing the base's workspace and inbox. The number of lenses is capped and enforced fail-closed.
What is not a principal
Groups, roles, and policies are first-class, but they are not principal kinds, keeping them out of the principal set is an explicit invariant, not an oversight:
- Groups are a first-class namespace with their own identifiers and membership records. They organize principals; they do not hold keys. (What was once modeled as an "organizational unit" is folded into group org-scope rather than being its own principal kind.)
- Roles are assignments attached to a principal within a scope, not principals themselves. A role assignment names the principal it applies to.
- Policies belong to the scope vocabulary: org, cell, service group, node, workspace, that answers "at what level does this policy apply?" rather than "who is acting?"
Identity beyond the base principals
Several identity-bearing constructs are layered on top of the base principals rather than being new kinds in the directory:
- Sub-agents carry an ephemeral, attenuated grant minted from a parent agent's authority, the model supplies intent, never identity (see Authorization and delegation).
- Workloads receive SPIFFE identity documents (X.509-SVIDs) and service access tokens with delegation chains for machine-to-machine calls.
- Cells hold a cell identity key and authenticate to peer cells over mutual TLS; a peer cell acts for no entity and binds no principal identity.
- External agents are represented by a signed agent card published through a JWKS endpoint, and remote entities are recorded in the directory's external-contacts surface as one of the principal kinds.
Principal kinds and the creation pipeline are described by mechanism. Cross-cell identity admission by certificate SAN is an area of active two-runtime work, the SAN grammar differs across runtimes, so cell-to-cell identity today keys on the verified service principal rather than a certificate-derived cell id.
Related topics
- The entity lifecycle, the full arc of a principal: create, provision (one act, many resources), active, and decommission.
- Authentication, how each principal proves its identity.
- Authorization and delegation, how authority flows to a principal and narrows as it goes.
- Governance (Deny-Closed), how grants to these principals are gated and revoked.