Glossary: identity and organizations
Terms for users, identity links and pins, organizations, and principals.
Published from docs/glossary/principals.md (GitHub)
Part of the glossary.
Identity Link
A public permalink that names one user’s exact identity keys. It encodes the identity trust domain (the API service), the user ID, and a SHA-256 fingerprint over a versioned, domain-separated tuple of both values plus the user’s ML-DSA-87 signing and ML-KEM-1024 encapsulation public keys. It holds no secret and grants no access, so it can be shared and reused.
Verifying a link fetches the user’s keys from the server, validates them, and
accepts them only if they hash to the link’s fingerprint, before anything is
pinned. A server that substitutes keys therefore fails verification instead of
being trusted on first use. The link is only as trustworthy as the channel that
delivered it: exchange it through one you already trust (in person, or a
messenger whose contact you know). Once verified, the keys are recorded as an
identity pin with link provenance. A link that disagrees
with an existing pin fails and changes nothing, and a link for another service
is refused before any fetch.
Only a link or self pin admits a user: adding a contact, a roster or group
member, or a share recipient. Copying another user’s link re-shares it only
from such a pin, never from an observed one.
Related docs:
Identity Pin
The durable, local record binding (identityTrustDomain, userId) to one
user’s signing and encapsulation public keys. Pins are never deleted and their
keys never change; any later key change is a hard failure before key use. Each
pin records its provenance: self (this device’s own keys), link (a
verified identity link), or observed (the server’s first
answer for a user that signed state already references). Provenance only
rises. Within a trust domain a signing key is pinned to at most one user.
Related docs:
Identity Trust Domain
The API service a user identity belongs to, written identityTrustDomain. It
defaults to the canonical absolute apiBaseUrl, including its base path; a
non-browser host with a relative API URL must supply an absolute
identityTrustDomain, and remote identity resolution
fails closed when no stable, host-controlled trust
domain can be established. Identity pins are keyed by
(identityTrustDomain, userId), and within one trust domain a signing key is
pinned to at most one user. An identity link encodes its
trust domain; verification always uses the configured API, and a link for
another service is refused before any fetch.
Related docs:
Managed Principal
A group or organization whose membership and key epoch are represented by a signed principal policy chain. Managed-principal grants fail closed when the policy state or member envelopes needed for verification are missing or stale.
Related docs:
Organization
The top-level ownership and policy boundary for user data. Registration creates
a default organization, reserved Admins and Members groups, and a
root container. The organization row stores adminGroupId
and memberGroupId. Reachability through Admins is org-admin authority.
Reachability through Members is organization membership. Org-manager directory
lifecycle is stored in organization roster entries
so disabled users can remain visible after access removal. Organization policy
commits authority, not container grants; org-manager
product roles come from the reserved groups.
Related docs:
Organization Admins Group
The reserved organization-scoped Admins group. Reachable users have
organization-admin authority, including admin-only org-manager mutations and
org-scoped principal policy successor signing when
the API verifies that authority.
Related docs:
Organization Members Group
The reserved organization-scoped Members group. Reachable users belong to the
organization. Active roster entries are
synchronized from this group’s signed reachability, but disabled roster entries
may remain visible without granting access. Admins is not nested into
Members — principals contain only users — so the policy write instead rejects
any managed principal naming a user who is not an active
roster entry, which keeps every admin an organization member.
Related docs:
Organization Read Model
The organization-scoped display and navigation data that the client keeps as
normalized SQLite projections and reconciles from one
cursor-ordered feed, GET /organizations/:organizationId/read-model. Every
authoritative mutation that changes it advances the
organization’s organization_read_model_heads cursor and, in
the same transaction, stamps each changed lane (directory, groups, group
memberships, grants, organization policy). A client without a cursor requests
an atomic snapshot; one with a cursor requests the lanes stamped after it. The
read model is not an authorization or cryptographic input: signed
principal policies, verified
access manifests, and
checkpoints remain authoritative. Sharing and
key-rotation probes therefore consume the organization policy’s signed directory
of current group heads, not the read model’s group lane.
Related docs:
Organization Roster Entry
An organization-scoped product row that records directory lifecycle state for a
user. It stores server-visible routing/status metadata such as status,
joinedAt, disabledAt, disabledByUserId, and optional profileDocumentId.
It does not store plaintext profile fields such as email, first name, or last
name; those belong in encrypted documents.
Related docs:
Principal
An entity that can receive access or key material. Users are principals with registered signing and encapsulation keys; groups and organizations are managed principals with signed policy state.
Related docs:
Principal Policy State
The signed state chain for a managed principal. It commits to membership, projection roots, key epoch, encrypted payload hash, signer, and predecessor state so clients can verify group or organization authority.
Related docs: