Users

Methods on this page are called as client.users.<method>(...) on a Goodmem instance.

Class — ai.pairsys.goodmem.client.api.UsersAPI (extends internal UsersAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

try (Goodmem client = Goodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    // client.users.<method>(...)
}

Async variants

Every method listed below also exists on ai.pairsys.goodmem.client.api.AsyncUsersAPI (accessed via asyncClient.users on an AsyncGoodmem) with the same parameter list, wrapped in CompletableFuture<T>. Paginated list methods return CompletableFuture<AsyncPage<T>>. See the async client guide for composition patterns.

import ai.pairsys.goodmem.client.AsyncGoodmem;

try (AsyncGoodmem asyncClient = AsyncGoodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    asyncClient.users.<method>(...)  // returns CompletableFuture<T>
}

Method Summary

Modifier and Type	Method	Description
`UserResponse`	`create(CreateUserRequest)`	Create a human user
`CreateUserEnrollmentResponse`	`createEnrollment(String, CreateUserEnrollmentRequest)`	Create a human-user enrollment
`void`	`delete(String)`	Delete a human user
`UserResponse`	`get(UsersGetOptions)`	Get a user by ID
`UserResponse`	`getByUsername(String, Map<String, Object>)`	Get user by username
`UserEnrollmentResponse`	`getEnrollment(String, String)`	Get a human-user enrollment
`Page<UserResponse>`	`list(Map<String, Object>)`	List human users
`Page<UserEnrollmentResponse>`	`listEnrollments(String, Map<String, Object>)`	List a human user's enrollments
`UserResponse`	`me()`	Get current user profile
`void`	`revokeEnrollment(String, String)`	Revoke a human-user enrollment
`UserResponse`	`update(String, UpdateUserRequest)`	Update a human user

Method Detail

`create(CreateUserRequest)`

UserResponse create(CreateUserRequest request)

Javadoc — create(CreateUserRequest)

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

request (CreateUserRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — UserResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

UserResponse userResponse = client.users.create(CreateUserRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/users' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "username": "alex",
    "displayName": "Alex Example",
    "labels": {
      "team": "search"
    }
  }'

`createEnrollment(String, CreateUserEnrollmentRequest)`

CreateUserEnrollmentResponse createEnrollment(String userId, CreateUserEnrollmentRequest request)

Javadoc — createEnrollment(String, CreateUserEnrollmentRequest)

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

request (CreateUserEnrollmentRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — CreateUserEnrollmentResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

CreateUserEnrollmentResponse createUserEnrollmentResponse = client.users.createEnrollment(CreateUserEnrollmentRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/users/{userId}/enrollments' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* CreateUserEnrollmentRequest fields, see Javadoc */ }'

`delete(String)`

void delete(String id)

Javadoc — delete(String)

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

id (String) — User UUID

Returns — None (HTTP 204).

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

client.users.delete("...");

REST equivalent

curl -X DELETE 'http://localhost:8080/v1/users/{id}' \
  -H "x-api-key: gm_..."

`get(UsersGetOptions)`

UserResponse get(UsersGetOptions opts)

Javadoc — get(UsersGetOptions)

Retrieves a user by ID or email address. Exactly one of id and email must be provided.

HTTP — GET /v1/users/{id}

Parameters

opts (UsersGetOptions) — options bag. Set exactly one of its fields (the compact constructor enforces "exactly one"). Mirrors Python's kwargs form and the AWS / GCP / Azure / OpenAI options-bag norm. The linked Javadoc lists every field.

Returns — UserResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

UserResponse userResponse = client.users.get(UsersGetOptions.builder().build());

REST equivalent

curl -X GET 'http://localhost:8080/v1/users/{id}' \
  -H "x-api-key: gm_..."

`getByUsername(String, Map<String, Object>)`

UserResponse getByUsername(String username, Map<String, Object> query)

Javadoc — getByUsername(String, Map<String, Object>)

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

username (String) — Exact username
query (Map<String, Object>) — query-string parameters; use Map.of() when none.

Returns — UserResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

UserResponse userResponse = client.users.getByUsername("...", java.util.Map.of());

REST equivalent

curl -X GET 'http://localhost:8080/v1/users/username/{username}' \
  -H "x-api-key: gm_..."

`getEnrollment(String, String)`

UserEnrollmentResponse getEnrollment(String userId, String enrollmentId)

Javadoc — getEnrollment(String, String)

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

(no parameters)

Returns — UserEnrollmentResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

UserEnrollmentResponse userEnrollmentResponse = client.users.getEnrollment();

REST equivalent

curl -X GET 'http://localhost:8080/v1/users/{userId}/enrollments/{enrollmentId}' \
  -H "x-api-key: gm_..."

`list(Map<String, Object>)`

Page<UserResponse> list(Map<String, Object> query)

Javadoc — list(Map<String, Object>)

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

query (Map<String, Object>) — query-string parameters; use Map.of() when none.

Returns — Page<UserResponse>

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

Page<UserResponse> page = client.users.list(java.util.Map.of());

REST equivalent

curl -X GET 'http://localhost:8080/v1/users' \
  -H "x-api-key: gm_..."

`listEnrollments(String, Map<String, Object>)`

Page<UserEnrollmentResponse> listEnrollments(String userId, Map<String, Object> query)

Javadoc — listEnrollments(String, Map<String, Object>)

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

query (Map<String, Object>) — query-string parameters; use Map.of() when none.

Returns — Page<UserEnrollmentResponse>

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

Page<UserEnrollmentResponse> page = client.users.listEnrollments(java.util.Map.of());

REST equivalent

curl -X GET 'http://localhost:8080/v1/users/{userId}/enrollments' \
  -H "x-api-key: gm_..."

`me()`

UserResponse me()

Javadoc — me()

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

(no parameters)

Returns — UserResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

UserResponse userResponse = client.users.me();

REST equivalent

curl -X GET 'http://localhost:8080/v1/users/me' \
  -H "x-api-key: gm_..."

`revokeEnrollment(String, String)`

void revokeEnrollment(String userId, String enrollmentId)

Javadoc — revokeEnrollment(String, String)

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

(no parameters)

Returns — None (HTTP 204).

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

client.users.revokeEnrollment();

REST equivalent

curl -X DELETE 'http://localhost:8080/v1/users/{userId}/enrollments/{enrollmentId}' \
  -H "x-api-key: gm_..."

`update(String, UpdateUserRequest)`

UserResponse update(String id, UpdateUserRequest request)

Javadoc — update(String, UpdateUserRequest)

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

id (String) — User UUID
request (UpdateUserRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — UserResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

UserResponse userResponse = client.users.update("...", UpdateUserRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X PUT 'http://localhost:8080/v1/users/{id}' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "displayName": "Alexandra Example"
    }
  }'

Errors

Every method on this page may throw the standard HTTP-error class hierarchy rooted at GoodmemException:

BadRequestException (400), AuthenticationException (401), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), UnprocessableEntityException (422), RateLimitException (429), InternalServerException (5xx), or the generic ApiException for any other 4xx/5xx. All are unchecked (RuntimeException). See Errors.

All error classes live in ai.pairsys.goodmem.client.errors and are unchecked (RuntimeException). Async siblings complete the returned CompletableFuture exceptionally with the same types, wrapped in CompletionException at await time. See Errors on the index for the full table.

Users

On this page