ServiceIdentities

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

Class — ai.pairsys.goodmem.client.api.ServiceIdentitiesAPI (extends internal ServiceIdentitiesAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

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

Async variants

Every method listed below also exists on ai.pairsys.goodmem.client.api.AsyncServiceIdentitiesAPI (accessed via asyncClient.service_identities 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.service_identities.<method>(...)  // returns CompletableFuture<T>
}

Method Summary

Modifier and Type	Method	Description
`ServiceIdentityResponse`	`create(CreateServiceIdentityRequest)`	Create a service identity
`void`	`delete(String)`	Delete a service identity
`ServiceIdentityResponse`	`get(String, Map<String, Object>)`	Get a service identity
`Page<ServiceIdentityResponse>`	`list(Map<String, Object>)`	List service identities
`TransferServiceIdentityOwnershipResponse`	`transferOwnership(String, TransferOwnershipRequest)`	Transfer service-identity ownership
`ServiceIdentityResponse`	`update(String, UpdateServiceIdentityRequest)`	Update a service identity

Method Detail

`create(CreateServiceIdentityRequest)`

ServiceIdentityResponse create(CreateServiceIdentityRequest request)

Javadoc — create(CreateServiceIdentityRequest)

Creates one production-workload identity owned by the authenticated human. No API key, role, grant, or authentication mapping is created implicitly.

HTTP — POST /v1/service-identities

Parameters

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

Returns — ServiceIdentityResponse

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

ServiceIdentityResponse serviceIdentityResponse = client.service_identities.create(CreateServiceIdentityRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/service-identities' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "production-indexer",
    "description": "Indexes newly uploaded memories",
    "labels": {
      "environment": "production"
    }
  }'

`delete(String)`

void delete(String id)

Javadoc — delete(String)

Permanently soft-deletes the principal. Its stored credentials remain audit records but can no longer authenticate because their subject is deleted. Repeating an authorized delete succeeds without rewriting audit data.

HTTP — DELETE /v1/service-identities/{id}

Parameters

id (String) — Service-identity 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.service_identities.delete("...");

REST equivalent

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

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

ServiceIdentityResponse get(String id, Map<String, Object> query)

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

Returns a service identity after applying READ_SERVICE_IDENTITY authority. includeDeleted permits an authorized caller to inspect a permanent tombstone; it does not grant additional authority.

HTTP — GET /v1/service-identities/{id}

Parameters

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

Returns — ServiceIdentityResponse

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

ServiceIdentityResponse serviceIdentityResponse = client.service_identities.get("...", java.util.Map.of());

REST equivalent

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

`list(Map<String, Object>)`

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

Javadoc — list(Map<String, Object>)

Requires LIST_SERVICE_IDENTITY on the GoodMem instance and READ_SERVICE_IDENTITY on each returned row. Owner and label filters, lifecycle filtering, authorization, and keyset pagination execute in PostgreSQL. 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/service-identities

Parameters

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

Returns — Page<ServiceIdentityResponse>

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<ServiceIdentityResponse> page = client.service_identities.list(java.util.Map.of());

REST equivalent

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

`transferOwnership(String, TransferOwnershipRequest)`

TransferServiceIdentityOwnershipResponse transferOwnership(String id, TransferOwnershipRequest request)

Javadoc — transferOwnership(String, TransferOwnershipRequest)

Transfers administrative ownership to another active principal. A service identity cannot own itself. The service identity's subject, immutable creator, credentials, grants, and roles are unchanged.

HTTP — POST /v1/service-identities/{id}:transferOwnership

Parameters

id (String) — Service-identity UUID
request (TransferOwnershipRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — TransferServiceIdentityOwnershipResponse

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

TransferServiceIdentityOwnershipResponse transferServiceIdentityOwnershipResponse = client.service_identities.transferOwnership("...", TransferOwnershipRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/service-identities/{id}:transferOwnership' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* TransferOwnershipRequest fields, see Javadoc */ }'

`update(String, UpdateServiceIdentityRequest)`

ServiceIdentityResponse update(String id, UpdateServiceIdentityRequest request)

Javadoc — update(String, UpdateServiceIdentityRequest)

Updates only fields present in the request. Empty description clears that optional field. Ownership changes use the dedicated transfer endpoint.

HTTP — PUT /v1/service-identities/{id}

Parameters

id (String) — Service-identity UUID
request (UpdateServiceIdentityRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — ServiceIdentityResponse

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

ServiceIdentityResponse serviceIdentityResponse = client.service_identities.update("...", UpdateServiceIdentityRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X PUT 'http://localhost:8080/v1/service-identities/{id}' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "description": "Indexes production knowledge sources"
    }
  }'

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.

ServiceIdentities

On this page