API Keys

API key lifecycle — create, list, update, soft-delete.

Namespace: Goodmem.Client.Api · Class: ApiKeysApi

Reach this surface as client.ApiKeys on a GoodmemClient. Every network method is asynchronous — it returns a Task<T> (or an IAsyncEnumerable<T> for pagination and streaming) and accepts a CancellationToken; the Async suffix marks the standard .NET Task-based async pattern.

Methods

CreateAsync

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.

Declaration

public Task<CreateApiKeyResponse> CreateAsync(CreateApiKeyRequest request, CancellationToken ct = default)

HTTP — POST /v1/apikeys

Parameters

Returns

Task<CreateApiKeyResponse> — an awaitable that resolves to CreateApiKeyResponse.

Exceptions

Example

var key = await client.ApiKeys.CreateAsync(
    new CreateApiKeyRequest
    {
        Labels = new Dictionary<string, string>
        {
            ["env"] = "docs",
            ["purpose"] = "sdk-doc-test",
        },
    }
);
Console.WriteLine(key.RawApiKey); // returned only once, at creation

ListAsync

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.

Declaration

public Task<ListApiKeysResponse> ListAsync(CancellationToken ct = default)

HTTP — GET /v1/apikeys

Parameters

Returns

Task<ListApiKeysResponse> — an awaitable that resolves to ListApiKeysResponse.

Exceptions

Example

var resp = await client.ApiKeys.ListAsync();
foreach (var key in resp.Keys)
    Console.WriteLine($"{key.ApiKeyId} {key.Status}");

UpdateAsync

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.

Declaration

public Task<ApiKeyResponse> UpdateAsync(string id, UpdateApiKeyRequest request, CancellationToken ct = default)

HTTP — PUT /v1/apikeys/{id}

Parameters

Returns

Task<ApiKeyResponse> — an awaitable that resolves to ApiKeyResponse.

Exceptions

Example

var updated = await client.ApiKeys.UpdateAsync(
    "your-api-key-id",
    new UpdateApiKeyRequest
    {
        MergeLabels = new Dictionary<string, string> { ["updated"] = "true" },
    }
);
Console.WriteLine(updated.ApiKeyId);

DeleteAsync

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.

Declaration

public Task DeleteAsync(string id, CancellationToken ct = default)

HTTP — DELETE /v1/apikeys/{id}

Parameters

Returns

Task — completes when the operation finishes; there is no response body.

Exceptions

Example

await client.ApiKeys.DeleteAsync("your-api-key-id");

Data Models

Types in the Goodmem.Client.Models namespace. Each row lists the C# property, its type, the JSON wire name, and a description.

CreateApiKeyRequest

Request parameters for creating a new API key.

CreateApiKeyResponse

Response returned when creating a new API key.

ApiKeyResponse

API key metadata without sensitive information.

ListApiKeysResponse

Response containing a list of API keys.

UpdateApiKeyRequest

Request parameters for updating an API key.