Built-in Roles

A role is a named, code-defined bundle of capabilities. A role assignment binds one principal, one role, and one resource: instance roles are assigned on the GoodMem instance itself, and memory-space roles are assigned on a single space. The role's capabilities then apply relative to that assigned resource, so a SPACE_ADMIN assignment on space X grants nothing on space Y.

Role definitions live in server code. A deployment cannot redefine what ADMIN means by editing a table; role names and numeric identifiers are stable API values, and the capability sets below are the complete definitions. Roles are one source of authority among several — direct grants, all-authenticated grants, and resource ownership are evaluated alongside them, and a scoped API key's ceiling still attenuates the result. See Roles, Grants, and Selectors for how these sources combine.

Each capability pairs an operation with a selector. Instance roles use the OWN and ANY selectors; memory-space roles use EXACT (the assigned space itself) and DIRECT_MEMBERS_OF (the memories directly contained by it). Selector semantics are defined in Operations and Selectors.

Role Catalog

Instance Roles

ROOT

ROOT marks the current instance owner and supplies no ordinary capabilities. The owner's authority — recovery-level access administration across the instance, and the exclusive right to transfer instance ownership — derives from ownership itself rather than from this assignment. ROOT cannot be assigned or revoked through the access-policy API; attempting either returns INVALID_ARGUMENT. The assignment moves only as part of an instance ownership transfer.

ADMIN

ADMIN is the broad instance administrator. It holds every resource operation below with both the OWN and ANY selectors:

It additionally holds these operations with ANY only:

ADMIN does not hold TRANSFER_INSTANCE_OWNERSHIP. Only the current instance owner can transfer the instance, and no role or grant can supply that authority.

USER

USER is the standard role for a person operating their own resources. The pattern: OWN for nearly everything, ANY for the instance-level LIST_* collection gates and for OCR_DOCUMENT. The ANY list capabilities permit invoking the list operation; each returned row must still pass the matching READ_* check, so a USER sees only rows they can read.

LIST_MEMORY carries OWN rather than ANY because it targets a space rather than the instance: a USER may enumerate memories in spaces they own.

USER holds no capability for creating, deleting, or listing human users, no MANAGE_USER_ENROLLMENT, no MANAGE_ACCESS, no provider-credential reads, and no ownership transfer. A USER still administers access policy on resources they own — that right derives from ownership rather than from the role.

Memory-Space Roles

Memory-space roles are assigned on one space. In the tables below, S is the assigned space. Each role includes everything the previous one grants.

SPACE_VIEWER

A viewer can read the space's configuration, enumerate its memories, and read them. That combination also satisfies both gates of semantic retrieval over S.

SPACE_CONTRIBUTOR

Viewer capabilities, plus:

SPACE_CONTENT_MANAGER

Contributor capabilities, plus:

SPACE_ADMIN

Content-manager capabilities, plus:

A SPACE_ADMIN configures the space, manages its content, and administers its access policy — including granting space roles to others and appointing another SPACE_ADMIN. No space role includes deleting the space or transferring its ownership. Deletion belongs to the space's owner and to instance administrators; transfer belongs to the owner, the instance owner, and holders of TRANSFER_RESOURCE_OWNERSHIP.

Provisioning Defaults

System initialization creates the first human and gives them two independent assignments: ROOT, mirroring instance ownership, and ADMIN, supplying ordinary administrative capabilities. An instance ownership transfer later moves only ROOT. The new owner does not implicitly become an ADMIN; they can use ownership-derived access administration to assign themselves the role. The former owner keeps any ADMIN assignment until it is revoked.

Assigning Roles

Role assignments are managed through the access-policy API. With the CLI:

# Instance role: no resource UUID
goodmem access-policy role-assignment assign \
  --principal <principal-uuid> \
  --role USER \
  --resource-kind INSTANCE

# Space role: names the space
goodmem access-policy role-assignment assign \
  --principal <principal-uuid> \
  --role SPACE_VIEWER \
  --resource-kind SPACE \
  --resource-id <space-uuid>

Spaces also expose a scoped shortcut that fixes the resource arguments:

goodmem space access role assign <space-uuid> \
  --principal <principal-uuid> \
  --role SPACE_VIEWER

Role tokens accept the short form (USER) or the full protobuf enum name (BUILT_IN_ROLE_USER); case and hyphens are normalized. Assigning or revoking a role requires MANAGE_ACCESS on the assignment's resource — the instance for instance roles, the space for space roles. See Share a Space for the common workflow.