Skip to main content

API Keys - Python SDK

client.keys manages API keys used to authenticate this SDK and other platform clients. Revealed plaintext values are secrets and must never be logged.

Overview​

Available Operations​

MethodDescription
list(owner_id=None)List API keys visible to the caller; admin callers may filter by owner.
create(body)Create an API key.
reveal(id)Reveal a key's plaintext value when policy permits.
update(id, body)Update description, active state, or expiration.
delete(id)Delete an API key.

list​

List API keys visible to the caller; admin callers may filter by owner.

Request​

Optional keyword-only owner_id.

Response​

list[ApiKeyResponse].

create​

Create an API key.

Request​

ApikeyRequest; required keyValue, with optional description, isActive, and expiresAt. The caller generates the key value.

Response​

ApiKeyResponse; may include one-time plaintextKey.

reveal​

Reveal a key's plaintext value when policy permits.

Request​

String id required.

Response​

str.

update​

Update description, active state, or expiration.

Request​

String id and ApikeyRequest required.

Response​

Updated ApiKeyResponse.

delete​

Delete an API key.

Request​

String id required.

Response​

bool.

Field Reference and Examples​

ApikeyRequest supports id, keyValue, isActive, description, expiresAt, and createdBy. The caller must generate and submit keyValue; normal users should not set ownership fields. ApiKeyResponse contains id, isActive, description, expiresAt, createdBy, userId, masked keyValue, and possibly one-time plaintextKey.

The response id is numeric while the key-management path accepts a string; convert it with str(...) before follow-up calls.

keys = client.keys.list()
created = client.keys.create({
    "keyValue": "sk-created-by-caller",
    "description": "automation key",
    "isActive": True,
})
key_id = str(created["id"])
plaintext = created.get("plaintextKey") or client.keys.reveal(key_id)
updated = client.keys.update(key_id, {
    "description": "renamed key",
    "isActive": True,
})
deleted = client.keys.delete(key_id)

All methods use the shared authentication and typed error behavior described in Response Conventions and Retry and Security.