Users

Python SDK reference for human users: enrollment management, creation, lookup, listing, updates, and deletion.

Methods on this page are called as client.users.<method>(...) where client is either a synchronous Goodmem or asynchronous AsyncGoodmem instance initialized below:

from goodmem import Goodmem
client = Goodmem(base_url='http://localhost:8080', api_key='gm_...')

from goodmem import AsyncGoodmem
client = AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...')

Create a human user

users.create(*, email: str, display_name: str = None, labels: dict[str, str] = None, user_id: str = None, username: str = None) → UserResponse

Creates one dormant human user after requiring instance-wide CREATE_USER authority. Creation does not issue a credential or create a role, grant, or authentication mapping.

Parameters:

email (str) — Unique, nonempty email address.
display_name (str, optional) — Optional human-facing display name.
labels (dict[str, str], optional) — Optional labels for organization and filtering. At most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].
user_id (str, format: uuid, optional) — Optional client-provided user UUID; generated by the server when omitted.
username (str, optional) — Optional unique username.

Returns:

UserResponse — Returns the user profile.

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

created_user = client.users.create(
    email="[email protected]",
    username="alex",
    display_name="Alex Example",
    labels={"team": "search"},
)

Get a user by ID or email

users.get(*, email: str = None, id: str = None, include_deleted: bool = None) → UserResponse

Retrieves a user by ID or email address. Exactly one of id and email must be provided. For getting your own profile, use client.users.me().

Parameters:

email (str, optional) — The user's email address. Mutually exclusive with id — exactly one must be provided.
id (str, optional) — The user's UUID. Mutually exclusive with email — exactly one must be provided.
include_deleted (bool, optional, server default=False) — Permit an authorized read of a permanent tombstone

Returns:

UserResponse — Returns the user profile.

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Examples

Example 1:

user = client.users.get(id="your-user-id")
print(user.email)

Example 2:

user = client.users.get(email="[email protected]")
print(user.user_id)

List human users

users.list(*, include_deleted: bool = None, include_enrollment_summary: bool = None, label: dict[str, str] = None, max_results: int = None, next_token: str = None) → Page[UserResponse]

Requires LIST_USER on the GoodMem instance and READ_USER on each returned row. Authorization, label filtering, lifecycle filtering, and keyset pagination run in PostgreSQL. include_deleted expands the lifecycle view but grants no access. include_enrollment_summary requests non-secret bootstrap posture only on active rows where MANAGE_USER_ENROLLMENT is independently authorized.

LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).

Parameters:

include_deleted (bool, optional, server default=False) — Include readable permanent tombstones
include_enrollment_summary (bool, optional, server default=False) — Request non-secret enrollment posture on active rows where the caller also has MANAGE_USER_ENROLLMENT
label (dict[str, str], optional) — Filter by label key-value pairs. Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).
max_results (int, format: int32, optional, server default=50) — Page size; defaults to 50 and must be between 1 and 1000
next_token (str, optional) — Opaque continuation token

Returns:

Page[UserResponse]

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

for user in client.users.list(max_results=25):
    print(user.user_id, user.email)

Update a human user

users.update(*, id: str, request: UpdateUserRequest | dict) → UserResponse

Updates only fields present in the request. Empty username or display_name values clear those optional fields. Updating a deleted user fails with 412.

Parameters:

id (str) — The unique identifier of the resource to update.
request (UpdateUserRequest | dict) — The update payload. Accepts a UpdateUserRequest instance or a plain dict with the same fields. Only specified fields will be modified.

Returns:

UserResponse — Returns the user profile.

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

updated_user = client.users.update(
    id=created_user.user_id,
    request={"display_name": "Alexandra Example"},
)

Delete a human user

users.delete(*, id: str) → None

Permanently soft-deletes the user and invalidates credentials acting for that subject. The GoodMem instance owner cannot be deleted; transfer ownership first. Repeating an authorized delete succeeds without rewriting audit data.

Parameters:

id (str) — User UUID

Returns:

None

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

client.users.delete(id=updated_user.user_id)

Create a human-user enrollment

users.create_enrollment(*, request: CreateUserEnrollmentRequest | dict, user_id: str) → CreateUserEnrollmentResponse

Creates a short-lived, one-time enrollment credential for an existing dormant human. Requires MANAGE_USER_ENROLLMENT with ANY or EXACT authority on the target user. The raw credential is returned only once. rotate_existing atomically revokes and replaces a live enrollment; an expired enrollment is replaced automatically.

Parameters:

request (CreateUserEnrollmentRequest | dict) — Update payload. Pass a CreateUserEnrollmentRequest instance or a plain dict (validated automatically).
user_id (str) — Human-user UUID

Returns:

CreateUserEnrollmentResponse

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

created = client.users.create_enrollment(
    user_id=user_id,
    request={"rotate_existing": True},
)
# Save created.enrollment_token now; it is returned only once.

Get user by username

users.get_by_username(*, username: str, include_deleted: bool = None) → UserResponse

Returns a user selected by exact username after applying READ_USER authority. include_deleted permits an authorized caller to inspect a permanent tombstone; it does not grant additional authority. Missing and unauthorized matches both return 404 so this guessable identifier cannot reveal whether a user exists.

Parameters:

username (str) — Exact username
include_deleted (bool, optional, server default=False) — Permit an authorized read of a permanent tombstone

Returns:

UserResponse — Returns the user profile.

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

user = client.users.get_by_username(username="alex")
print(user.email)

Get a human-user enrollment

users.get_enrollment(*, enrollment_id: str, user_id: str) → UserEnrollmentResponse

Returns non-secret metadata for one current or historical enrollment. The target user is resolved before the enrollment, and MANAGE_USER_ENROLLMENT with ANY or EXACT authority on that user is required. Raw enrollment tokens are never returned.

Parameters:

enrollment_id (str) — Enrollment UUID
user_id (str) — Human-user UUID

Returns:

UserEnrollmentResponse

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

enrollment = client.users.get_enrollment(
    user_id=user_id,
    enrollment_id=created.enrollment.enrollment_id,
)

List a human user's enrollments

users.list_enrollments(*, user_id: str, max_results: int = None, next_token: str = None) → Page[UserEnrollmentResponse]

Returns one newest-first page containing pending, expired, consumed, and revoked enrollment metadata. MANAGE_USER_ENROLLMENT with ANY or EXACT authority on the target user is required. The page never contains raw credentials.

Parameters:

user_id (str) — Human-user UUID
max_results (int, format: int32, optional, server default=50) — Page size; defaults to 50 and must be between 1 and 1000
next_token (str, optional) — Opaque continuation token

Returns:

Page[UserEnrollmentResponse]

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

for enrollment in client.users.list_enrollments(user_id=user_id):
    print(enrollment.enrollment_id, enrollment.status)

Get current user profile

users.me() → UserResponse

Returns the human-user profile associated with the authenticated principal. Service principals do not have a human-user profile.

Returns:

UserResponse — Returns the user profile.

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

user = client.users.me()
print(user.email)

Revoke a human-user enrollment

users.revoke_enrollment(*, enrollment_id: str, user_id: str) → None

Permanently revokes one outstanding enrollment after requiring MANAGE_USER_ENROLLMENT on its target user. Repeating an authorized revocation succeeds without replacing its original audit provenance. Consumed enrollments cannot be revoked.

Parameters:

enrollment_id (str) — Enrollment UUID
user_id (str) — Human-user UUID

Returns:

None

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

client.users.revoke_enrollment(
    user_id=user_id,
    enrollment_id=enrollment.enrollment_id,
)

Async usage: client.users exposes the same methods on AsyncGoodmem; use await / async for as needed.

Data Models

All data models are pydantic v2 models. Fields are shown with their Python attribute names; JSON responses use camelCase aliases (e.g., owner_id → ownerId).

UserResponse

A durable human user profile and its lifecycle metadata.

user_id (str) — OUTPUT_ONLY; immutable user UUID.
email (str) — OUTPUT_ONLY; unique email address.
display_name (str, optional) — OUTPUT_ONLY; optional human-facing display name.
username (str, optional) — OUTPUT_ONLY; optional unique username.
labels (dict[str, str]) — OUTPUT_ONLY; mutable labels attached to the user principal. At most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].
enrollment_summary (UserEnrollmentSummary, optional) — OUTPUT_ONLY; enrollment posture when requested and independently authorized.
deleted_at (int, optional) — OUTPUT_ONLY; permanent deletion time in milliseconds, absent while active.
deleted_by_id (str, optional) — OUTPUT_ONLY; exact deleting actor UUID, absent while active.
created_at (int) — OUTPUT_ONLY; creation time in milliseconds since the epoch.
updated_at (int) — OUTPUT_ONLY; most recent mutation time in milliseconds since the epoch.
created_by_id (str) — OUTPUT_ONLY; exact creating actor UUID.
updated_by_id (str) — OUTPUT_ONLY; exact actor UUID for the most recent mutation.

UserEnrollmentSummary

Non-secret enrollment posture for one active human user.

bootstrap_eligible (bool) — Whether no enrollment has been consumed and the user has no subject API key.
open_enrollment_status (Literal['PENDING', 'EXPIRED'], optional) — State of the open enrollment, when one exists; present exactly with open_enrollment_expires_at.
open_enrollment_expires_at (int, optional) — Exclusive open-enrollment completion deadline in epoch milliseconds; present exactly with open_enrollment_status.

UpdateUserRequest

Updates explicitly present profile fields. Empty username or display_name clears that optional field; an omitted field remains unchanged.

email (str, optional) — Replacement email. A present empty value is invalid.
username (str, optional) — Replacement username. An empty string clears the username.
display_name (str, optional) — Replacement display name. An empty string clears the display name.
replace_labels (dict[str, str], optional) — Complete replacement label map; an empty map clears all labels and is mutually exclusive with merge_labels. At most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].
merge_labels (dict[str, str], optional) — Labels to upsert; must contain at least one entry and is mutually exclusive with replace_labels. The final stored map may contain at most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].

CreateUserEnrollmentRequest

Options for issuing a one-time enrollment credential to the user named by the request path.

enrollment_id (str, optional) — Optional client-provided enrollment UUID; generated when omitted.
rotate_existing (bool, optional) — Whether an existing live enrollment may be revoked and atomically replaced.

CreateUserEnrollmentResponse

New enrollment metadata and its one-time raw enrollment credential.

enrollment (UserEnrollmentResponse) — OUTPUT_ONLY; non-secret metadata for the created enrollment.
enrollment_token (str) — OUTPUT_ONLY; one-time raw enrollment credential. Save and deliver it securely.

UserEnrollmentResponse

Non-secret lifecycle metadata for a human user's one-time enrollment credential.

enrollment_id (str) — OUTPUT_ONLY; immutable enrollment UUID.
user_id (str) — OUTPUT_ONLY; UUID of the human user invited to enroll.
credential_prefix (str) — OUTPUT_ONLY; non-secret prefix that identifies the enrollment credential safely.
status (Optional[Literal['PENDING', 'EXPIRED', 'CONSUMED', 'REVOKED']]) — OUTPUT_ONLY; current derived enrollment lifecycle state.
expires_at (int) — OUTPUT_ONLY; exclusive completion deadline in milliseconds since epoch.
consumed_api_key_id (str, optional) — OUTPUT_ONLY; initial API-key UUID, present after consumption.
created_at (int) — OUTPUT_ONLY; enrollment issuance time in milliseconds since epoch.
consumed_at (int, optional) — OUTPUT_ONLY; first-completion time, absent before consumption.
revoked_at (int, optional) — OUTPUT_ONLY; permanent revocation time, absent while unrevoked.
created_by_id (str) — OUTPUT_ONLY; exact principal or API-key actor that issued the enrollment.
revoked_by_id (str, optional) — OUTPUT_ONLY; exact revoking actor UUID, absent while unrevoked.

Equivalent REST calls

Equivalent REST calls

Equivalent REST calls

On this page