API Keys

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

Class — ai.pairsys.goodmem.client.api.ApikeysAPI (extends internal ApikeysAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

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

Async variants

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

Method Summary

Modifier and Type	Method	Description
`CreateApiKeyResponse`	`create(CreateApiKeyRequest)`	Create a new API key
`void`	`delete(String)`	Delete an API key
`ApiKeyResponse`	`get(String)`	Get an API key
`Page<ApiKeyResponse>`	`list(ApiKeyListOptions)`	List API keys
`ApiKeyResponse`	`update(String, UpdateApiKeyRequest)`	Update an API key

Method Detail

`create(CreateApiKeyRequest)`

CreateApiKeyResponse create(CreateApiKeyRequest request)

Javadoc — create(CreateApiKeyRequest)

Issues a new API key and returns its raw value exactly once. Omitted subject and authorityMode create a self-issued human key that inherits the subject's live authority. A SCOPED key requires a nonempty immutable ceiling, and every ceiling rule must be conservatively covered by both the subject's live authority and the issuing credential's effective authority. A scoped issuer can create only scoped children. SERVICE subjects require SCOPED mode and MANAGE_ACCESS on the service identity. AUTHORIZATION: Requires CREATE_API_KEY on the proposed credential; subject and ceiling checks are repeated by the final insertion statement.

HTTP — POST /v1/apikeys

Parameters

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

Returns — CreateApiKeyResponse

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

CreateApiKeyResponse createApiKeyResponse = client.apikeys.create(CreateApiKeyRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/apikeys' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "labels": {
      "env": "docs",
      "purpose": "sdk-doc-test"
    }
  }'

`delete(String)`

void delete(String id)

Javadoc — delete(String)

Delete an API key

Permanently revokes an API key and immediately rejects it for future authentication. The durable credential and audit history remain stored. This operation requires DELETE_API_KEY and records the revocation time and actor; it cannot be undone. PUT /v1/apikeys/{id} with status=INACTIVE performs the same permanent revocation.

HTTP — DELETE /v1/apikeys/{id}

Parameters

id (String) — The UUID of the API key to delete

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.apikeys.delete("...");

REST equivalent

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

`get(String)`

ApiKeyResponse get(String id)

Javadoc — get(String)

Returns complete non-secret metadata for one existing credential after requiring effective READ_API_KEY authority. The immutable ceiling is always complete and ceilingOmitted is false. Raw key material and hashes are never returned.

HTTP — GET /v1/apikeys/{id}

Parameters

id (String) — API-key UUID

Returns — ApiKeyResponse

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

ApiKeyResponse apiKeyResponse = client.apikeys.get("...");

REST equivalent

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

`list(ApiKeyListOptions)`

Page<ApiKeyResponse> list(ApiKeyListOptions options)

Javadoc — list(ApiKeyListOptions)

Retrieves one UUID-ordered page of API keys discoverable under the authenticated principal's effective API-key policy. Subject, owner, and lifecycle filters are applied after authorization. FULL includes complete immutable ceilings; BASIC omits them, sets ceilingOmitted=true, and permits larger pages. Raw key values and key hashes are never returned.

HTTP — GET /v1/apikeys

Parameters

options (ApiKeyListOptions, optional) — typed query parameters; pass null for an empty filter set. The linked Javadoc lists every field.

Returns — Page<ApiKeyResponse>

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<ApiKeyResponse> page = client.apikeys.list(ApiKeyListOptions.builder().build());

REST equivalent

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

`update(String, UpdateApiKeyRequest)`

ApiKeyResponse update(String id, UpdateApiKeyRequest request)

Javadoc — update(String, UpdateApiKeyRequest)

Updates an existing API key's labels or lifecycle status. Key ID, subject, ownership, key material, validity window, and creation audit fields remain immutable. Label changes require UPDATE_API_KEY; setting status=INACTIVE permanently revokes the key and requires DELETE_API_KEY; a request doing both requires both operations. Revoked keys cannot be reactivated. Side effects include updating administrative audit fields and, for revocation, recording the revocation time and actor.

HTTP — PUT /v1/apikeys/{id}

Parameters

id (String) — The UUID of the API key to update
request (UpdateApiKeyRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — ApiKeyResponse

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

ApiKeyResponse apiKeyResponse = client.apikeys.update("...", UpdateApiKeyRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X PUT 'http://localhost:8080/v1/apikeys/{id}' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mergeLabels": {
      "updated": "true"
    }
  }'

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.

API Keys

On this page