Users and Service Identities

Every authorized request in GoodMem is made by a principal. A principal is a durable identity: it can own resources, hold grants and role assignments, and appear in audit records. There are two kinds. A human user represents a person. A service identity represents a production workload — a retrieval service, an ingestion pipeline, an agent.

The two kinds share the same machinery: creation rules, soft deletion, audit fields, list pagination. They differ in what they represent and how they authenticate.

What Creation Does

Creating a principal creates an identity and nothing else. No API key is issued, no role is assigned, no grant is created. Identity, policy, and credentials are three separate security decisions, often made by different people at different times, and each leaves its own audit record. A freshly created user who somehow authenticated could do very little, which is the intended starting point.

A working human account is therefore assembled in steps: create the user, assign the USER role, create an enrollment credential, and let the person redeem it. The goodmem user onboard command runs the first three steps in sequence; see Onboard a User.

A working workload follows the same pattern: create the service identity, grant it exactly the authority it needs, and issue a scoped API key whose ceiling matches. See Set Up a Service Identity.

Only a human can create a service identity, and the creating human is always its initial owner. An administrator provisioning a workload for someone else creates it and then transfers ownership; the create call does not accept a different proposed owner.

Enrollment

A newly created human has no credential and no way to call the API. An administrator closes that gap by creating an enrollment credential: a one-time secret permanently bound to that person, redeemable only before the person holds any API key. It is not an API key, a principal, or an ordinary authentication mechanism — presented to any normal endpoint, it authorizes nothing. Redeeming it publishes the person's first API key and consumes the credential.

At most one enrollment can be open for a person at a time. Rotating it revokes the old credential and creates the replacement in one step, and an administrator can revoke an open enrollment outright. The administrator's side is covered in Onboard a User; the redeeming side in Redeem an Enrollment.

Deletion Is a Tombstone

Deleting a principal writes a permanent tombstone. The UUID stays occupied forever, the profile rows remain stored, and there is no restore operation. Repeating an authorized delete succeeds as a no-op; it cannot resurrect anything or overwrite the original deletion record.

Deletion rewrites nothing else. Grants and role assignments remain in history but stop having any effect. API keys are not marked revoked. Resource owner columns keep pointing where they pointed. The keys stop working anyway, because authentication requires an active subject: a key whose subject is a tombstone authenticates nothing, even though its own revocation state is untouched. The distinction is deliberate — audit history records what was revoked and what was abandoned, and those are different facts.

Normal reads and lists return active principals only. Administrative history requests can ask for deleted rows with an explicit include-deleted option. The option widens what a query may return; a tombstone is still subject to the same read checks as anything else.

Production Continuity

People leave. If production authority hangs off a person's account, it leaves with them. Service identities exist so that it does not.

Suppose Sarah creates a service identity called prod-search, grants it read access to the spaces it serves, and issues it a scoped key. Later Sarah's account is deleted. Her own keys stop authenticating. prod-search remains active, its grants remain live, and its keys keep working — including keys Sarah issued, because a key records its issuer only as audit provenance. Retrieval does not notice that Sarah is gone.

Ownership and Orphans

Every resource has exactly one authorization owner. Human user records own themselves. A new service identity, space, or API key is owned by the human who created it, until ownership is explicitly transferred.

When an owner is deleted, the resources it owned keep pointing at the tombstone. GoodMem does not reassign them, and there is no rule that quietly makes the instance owner the new owner. A tombstone-owned space still works — its memories are still readable by whoever holds the right grants — but nobody's OWN permissions cover it anymore.

Repair is an explicit ownership transfer. The current owner, the current instance owner, or an instance administrator can move a resource to an active principal. A service identity can be transferred to a human or to a different service identity, never to itself. The transfer changes the owner and the update audit fields; roles, grants, keys, subject identity, and creator provenance stay put.

The Instance Owner

Exactly one active human owns the GoodMem instance. Ownership carries a recovery right: the instance owner can always administer access policy on every resource, including tombstone-owned ones, and that right cannot be revoked by any grant change.

The current instance owner cannot be deleted. Ownership must first be transferred to another active human, after which the former owner can be deleted like anyone else. Since the instance always has an active human owner, the last active human cannot be deleted either.

ROOT is a mirror of instance ownership, carries no ordinary capabilities, and cannot be assigned through the API; it moves when ownership moves. ADMIN is an ordinary role assignment and does not move with ownership. A new instance owner who wants day-to-day administrative capabilities assigns themselves ADMIN, using the access-policy authority that ownership already provides.

Names and Identifiers

Email addresses, usernames, and service-identity display names are unique across the full history of the instance, tombstones included. Deleting prod-search does not free the name prod-search.

Client-provided UUIDs follow the same rule: an identifier names one logical resource, permanently. Soft deletion keeps it occupied, so a deleted principal cannot be recreated under the same UUID.

See Also

• Security Model — how a request's authority is evaluated
• API Keys and Ceilings — subjects, issuers, owners, and scoped keys
• Roles, Grants, and Selectors — where a principal's authority comes from
• Built-in Roles — what USER, ADMIN, and the space roles contain