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

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.

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

GetAsync

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.

Declaration

public Task<ApiKeyResponse> GetAsync(string id, CancellationToken ct = default)

HTTP — GET /v1/apikeys/{id}

Parameters

Returns

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

Exceptions

Example

var key = await client.ApiKeys.GetAsync("your-api-key-id");
Console.WriteLine($"{key.ApiKeyId} {key.LifecycleState}");

ListAsync

Requires LIST_API_KEY on the singleton instance, then retrieves one UUID-ordered page containing only credentials that independently pass READ_API_KEY. Both gates use the authenticated principal's live authority and any scoped-key ceiling. 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.

Declaration

public IAsyncEnumerable<ApiKeyResponse> ListAsync(ApiKeysListOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/apikeys

Parameters

Returns

IAsyncEnumerable<ApiKeyResponse> — an async stream; await foreach yields each ApiKeyResponse across pages / events.

Exceptions

Example

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

UpdateAsync

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.

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 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.

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.

ListApiKeysResponse

One page of API keys discoverable to the authenticated principal.

UpdateApiKeyRequest

Request parameters for updating an API key.