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>

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

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

Returns: Promise<void>

Example

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

client.apikeys.list

client.apikeys.list(requestOptions?: RequestOptions): Promise<Array<ApiKeyResponseShape>>

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

Returns: Promise<Array<ApiKeyResponseShape>>

Example

for (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 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

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

ApiKeyResponse

API key metadata without sensitive information.

CreateApiKeyRequest

Request parameters for creating a new API key.

CreateApiKeyResponse

Response returned when creating a new API key.

ListApiKeysResponse

Response containing a list of API keys.

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.

ApiKeyResponseShape

CreateApiKeyResponseShape

ListApiKeysResponseShape