API keys

Issue, list, update, and revoke API keys for your organization. The full key string (pk_live_...) is returned on creation, and can be shown again from Settings (once per sign-in, members and above, audited).

There is no pictograph CLI group for API keys - issue them in the web app (Settings → API Keys) or through the SDK / REST below. These routes live at /api/v1/api-keys/, not under /developer/. SDK source: resources/api_keys.py.

An API key may only address its own organization. Naming a different one is a 403.

list

Metadata only, no key strings.

Source: ApiKeys.list

for key in client.api_keys.list():
    print(key.name, key.role, key.key_prefix, key.last_used_at)

curl -s "https://api.pictograph.io/api/v1/api-keys/" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[ApiKey]

class ApiKey(BaseModel):
    """API key metadata returned by list/get/update endpoints."""
    id: str
    organization_id: str
    name: str
    key_prefix: str
    role: Literal['viewer', 'member', 'admin', 'owner']
    rate_limit: int
    is_active: bool
    last_used_at: datetime | None = None
    expires_at: datetime | None = None
    created_at: datetime

create

Issue a new key. The secret is returned only here - persist it immediately. Requires admin or owner role.

Source: ApiKeys.create

created = client.api_keys.create(
    name="ci-pipeline",
    role="member",
)
print("Save this:", created.api_key)   # viewable again from Settings

curl -s -X POST "https://api.pictograph.io/api/v1/api-keys/" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organization_id": "<org-uuid>", "name": "ci-pipeline", "role": "member"}'

Returns CreatedApiKey

class CreatedApiKey(BaseModel):
    """Response from ApiKeys.create - includes the secret one time only."""
    api_key: str
    key_id: str
    key_prefix: str
    name: str
    role: Literal['viewer', 'member', 'admin', 'owner']
    rate_limit: int
    expires_at: datetime | None = None
    created_at: datetime

get

Metadata for a single key. No secret is returned.

Source: ApiKeys.get

key = client.api_keys.get(
    key_id="c7d8e9f0-1a2b-4c34-8d5e-6f708192a3b4",
)
print(key.role, key.created_at, key.last_used_at)

curl -s "https://api.pictograph.io/api/v1/api-keys/$KEY_ID" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns ApiKey

class ApiKey(BaseModel):
    """API key metadata returned by list/get/update endpoints."""
    id: str
    organization_id: str
    name: str
    key_prefix: str
    role: Literal['viewer', 'member', 'admin', 'owner']
    rate_limit: int
    is_active: bool
    last_used_at: datetime | None = None
    expires_at: datetime | None = None
    created_at: datetime

update

Patch name, rate_limit, or is_active. At least one is required, or the SDK raises ValueError. A key’s role is immutable - to change a role, create a new key and delete the old one. Requires admin or owner role.

Source: ApiKeys.update

client.api_keys.update(
    key_id="c7d8e9f0-1a2b-4c34-8d5e-6f708192a3b4",
    name="renamed",
    rate_limit=10000,
)
client.api_keys.update(
    key_id="c7d8e9f0-1a2b-4c34-8d5e-6f708192a3b4",
    is_active=False,
)

curl -s -X PATCH "https://api.pictograph.io/api/v1/api-keys/$KEY_ID" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "renamed", "rate_limit": 10000}'

Returns ApiKey

class ApiKey(BaseModel):
    """API key metadata returned by list/get/update endpoints."""
    id: str
    organization_id: str
    name: str
    key_prefix: str
    role: Literal['viewer', 'member', 'admin', 'owner']
    rate_limit: int
    is_active: bool
    last_used_at: datetime | None = None
    expires_at: datetime | None = None
    created_at: datetime

delete

Revoke a key permanently. In-flight requests using it fail with 401 AuthError once revocation propagates (under a second). Cannot be undone.

Source: ApiKeys.delete

client.api_keys.delete(
    key_id="c7d8e9f0-1a2b-4c34-8d5e-6f708192a3b4",
)

curl -s -X DELETE "https://api.pictograph.io/api/v1/api-keys/$KEY_ID" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns None

Role hierarchy

These endpoints all require admin or owner, and a key can only create keys of equal or lower role.

Common errors