API Keys

API key lifecycle management.

Methods on this page are called through client.apikeys.

client.apikeys.create

client.apikeys.create(request: CreateApiKeyRequest, requestOptions?: RequestOptions): Promise<CreateApiKeyResponseShape>

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

Returns: Promise<CreateApiKeyResponseShape>

Example

const apiKey = await client.apikeys.create({ labels: { env: "docs" } });
console.log(apiKey.rawApiKey);

client.apikeys.delete

client.apikeys.delete(id: string, requestOptions?: RequestOptions): Promise<void>

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 protected lifecycle transition.

HTTP: DELETE /v1/apikeys/{id}

Parameters

Returns: Promise<void>

Example

await client.apikeys.delete("your-api-key-id");

client.apikeys.get

client.apikeys.get(id: string, requestOptions?: RequestOptions): Promise<ApiKeyResponseShape>

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

Returns: Promise<ApiKeyResponseShape>

Example

const fetchedApiKey = await client.apikeys.get("your-api-key-id");
console.log(fetchedApiKey.apiKeyId, fetchedApiKey.lifecycleState);

client.apikeys.list

client.apikeys.list(options?: ApikeysListOptions, requestOptions?: RequestOptions): Promise<Page<ApiKeyResponseShape>>

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.

HTTP: GET /v1/apikeys

Parameters

Returns: Promise<Page<ApiKeyResponseShape>>

Example

for await (const key of await client.apikeys.list()) {
  console.log(key.apiKeyId, key.status);
}

client.apikeys.update

client.apikeys.update(id: string, request: UpdateApiKeyRequest, requestOptions?: RequestOptions): Promise<ApiKeyResponseShape>

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

Returns: Promise<ApiKeyResponseShape>

Example

const updatedKey = await client.apikeys.update("your-api-key-id", {
  status: "INACTIVE",
  mergeLabels: { rotated: "true" },
});
console.log(updatedKey.status);

Data Models

Interfaces

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.

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

CreateApiKeyResponseShape

ListApiKeysResponseShape