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 Detail

create(CreateApiKeyRequest)

CreateApiKeyResponse create(CreateApiKeyRequest request)

Creates a new API key for authenticating with the API. New keys start in ACTIVE status and can be used immediately for authentication. The response includes the one-time raw API key value which will not be retrievable later - clients must save this value as it cannot be recovered. Requires CREATE_APIKEY_OWN permission (or CREATE_APIKEY_ANY for admin users). Side effects include generating cryptographically secure key material, recording creation timestamp, and tracking creator ID. Returns INVALID_ARGUMENT if expires_at is set to a time in the past.

HTTP — POST /v1/apikeys

Parameters

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

Returns — CreateApiKeyResponse

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)

Delete an API key

Permanently deletes an API key. This operation cannot be undone and immediately invalidates the key for all future authentication attempts. TIP: For reversible deactivation, use PUT /v1/apikeys/{id} with status=INACTIVE instead. Requires DELETE_APIKEY_OWN permission for keys you own (or DELETE_APIKEY_ANY for admin users to delete any user's keys). Side effects include permanently removing the key record from the database and immediate authentication invalidation.

HTTP — DELETE /v1/apikeys/{id}

Parameters

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

Returns — None (HTTP 204).

Example

client.apikeys.delete("...");

REST equivalent

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

list()

List<ApiKeyResponse> list()

Retrieves a list of API keys belonging to the authenticated user. The list includes metadata about each key but not the actual key values or key hashes for security reasons. Requires LIST_APIKEY_OWN permission (or LIST_APIKEY_ANY for admin users to view keys from any user). This is a read-only operation with no side effects.

HTTP — GET /v1/apikeys

Parameters

(no parameters)

Returns — List``<ApiKeyResponse>

Example

List<ApiKeyResponse> list = client.apikeys.list();

REST equivalent

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

update(String, UpdateApiKeyRequest)

ApiKeyResponse update(String id, UpdateApiKeyRequest request)

Updates an existing API key with new values for status or labels. IMPORTANT: Key ID, user ownership, key material, and audit fields cannot be modified - only status (ACTIVE/INACTIVE) and labels are mutable. Requires UPDATE_APIKEY_OWN permission for keys you own (or UPDATE_APIKEY_ANY for admin users to modify any user's keys). Side effects include updating the updated_at timestamp and recording the updater's user ID. This operation is idempotent - repeated identical requests have no additional effect.

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

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.