Users

User lookup.

Methods on this page are called through client.users.

client.users.create

client.users.create(request: CreateUserRequest, requestOptions?: RequestOptions): Promise<UserResponseShape>

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.

HTTP: POST /v1/users

Parameters

Returns: Promise<UserResponseShape>

Example

const createdUser = await client.users.create({
  email: "[email protected]",
  username: "alex",
  displayName: "Alex Example",
  labels: { team: "search" },
});

client.users.createEnrollment

client.users.createEnrollment(userId: string, request: CreateUserEnrollmentRequest, requestOptions?: RequestOptions): Promise<CreateUserEnrollmentResponseShape>

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. rotateExisting atomically revokes and replaces a live enrollment; an expired enrollment is replaced automatically.

HTTP: POST /v1/users/{userId}/enrollments

Parameters

Returns: Promise<CreateUserEnrollmentResponseShape>

Example

const createdEnrollment = await client.users.createEnrollment(createdUser.userId, {
  rotateExisting: true,
});
// Save createdEnrollment.enrollmentToken now; it is returned only once.

client.users.delete

client.users.delete(id: string, requestOptions?: RequestOptions): Promise<void>

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.

HTTP: DELETE /v1/users/{id}

Parameters

Returns: Promise<void>

Example

await client.users.delete(updatedUser.userId);

client.users.get

client.users.get(options?: UsersGetOptions, requestOptions?: RequestOptions): Promise<UserResponseShape>

Returns a user selected by UUID after applying READ_USER authority. includeDeleted permits an authorized caller to inspect a permanent tombstone; it does not grant additional authority.

HTTP: GET /v1/users/{id}

Parameters

Returns: Promise<UserResponseShape>

Example

Example 1:

const userById = await client.users.get({ id: "your-user-id" });
console.log(userById.email);

Example 2:

const userByEmail = await client.users.get({ email: "[email protected]" });
console.log(userByEmail.userId);

client.users.getByUsername

client.users.getByUsername(username: string, options?: UsersGetByUsernameOptions, requestOptions?: RequestOptions): Promise<UserResponseShape>

Returns a user selected by exact username after applying READ_USER authority. includeDeleted 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.

HTTP: GET /v1/users/username/{username}

Parameters

Returns: Promise<UserResponseShape>

Example

const userByUsername = await client.users.getByUsername("alex");
console.log(userByUsername.email);

client.users.getEnrollment

client.users.getEnrollment(userId: string, enrollmentId: string, requestOptions?: RequestOptions): Promise<UserEnrollmentResponseShape>

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.

HTTP: GET /v1/users/{userId}/enrollments/{enrollmentId}

Parameters

Returns: Promise<UserEnrollmentResponseShape>

Example

const enrollment = await client.users.getEnrollment(
  createdUser.userId,
  createdEnrollment.enrollment.enrollmentId,
);

client.users.list

client.users.list(options?: UsersListOptions, requestOptions?: RequestOptions): Promise<Page<UserResponseShape>>

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. includeDeleted expands the lifecycle view but grants no access. includeEnrollmentSummary 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).

HTTP: GET /v1/users

Parameters

Returns: Promise<Page<UserResponseShape>>

Example

for await (const user of await client.users.list({ maxResults: 25 })) {
  console.log(user.userId, user.email);
}

client.users.listEnrollments

client.users.listEnrollments(userId: string, options?: UsersListEnrollmentsOptions, requestOptions?: RequestOptions): Promise<Page<UserEnrollmentResponseShape>>

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.

HTTP: GET /v1/users/{userId}/enrollments

Parameters

Returns: Promise<Page<UserEnrollmentResponseShape>>

Example

for await (const enrollment of await client.users.listEnrollments(createdUser.userId)) {
  console.log(enrollment.enrollmentId, enrollment.status);
}

client.users.me

client.users.me(requestOptions?: RequestOptions): Promise<UserResponseShape>

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

HTTP: GET /v1/users/me

Parameters

Returns: Promise<UserResponseShape>

Example

const me = await client.users.me();
console.log(me.email, me.userId);

client.users.revokeEnrollment

client.users.revokeEnrollment(userId: string, enrollmentId: string, requestOptions?: RequestOptions): Promise<void>

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.

HTTP: DELETE /v1/users/{userId}/enrollments/{enrollmentId}

Parameters

Returns: Promise<void>

Example

await client.users.revokeEnrollment(createdUser.userId, enrollment.enrollmentId);

client.users.update

client.users.update(id: string, request: UpdateUserRequest, requestOptions?: RequestOptions): Promise<UserResponseShape>

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

HTTP: PUT /v1/users/{id}

Parameters

Returns: Promise<UserResponseShape>

Example

const updatedUser = await client.users.update(createdUser.userId, {
  displayName: "Alexandra Example",
});

Data Models

Interfaces

CreateUserEnrollmentRequest

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

CreateUserEnrollmentResponse

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

CreateUserRequest

Creates a human user without creating a credential, role assignment, grant, or external authentication mapping.

ListUserEnrollmentsResponse

One stable page of a human user's enrollment history.

ListUsersResponse

One authorization-filtered page of human users.

UpdateUserRequest

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

UserEnrollmentResponse

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

UserEnrollmentSummary

Non-secret enrollment posture for one active human user.

UserResponse

A durable human user profile and its lifecycle metadata.

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

CreateUserEnrollmentResponseShape

ListUserEnrollmentsResponseShape

ListUsersResponseShape

UserEnrollmentResponseShape

UserEnrollmentSummaryResponseShape

UserResponseShape