API keys

Use these endpoints to issue, list, update, and revoke API keys for your organization. The full key string (pk_live_…) is returned only once on creation — store it immediately.

Every example below shows the Python SDK call and the equivalent raw REST request. The REST examples authenticate with an X-API-Key header; set PICTOGRAPH_API_KEY in your shell to copy-and-run them. Note these routes live at /api/v1/api-keys/ (not under /developer/).

from pictograph import Client
client = Client()  # reads PICTOGRAPH_API_KEY

list

List API keys for the organization. Returns metadata only — no full key strings. organization_id defaults to the calling key’s own org; pass it explicitly only when listing keys for a different org you also administer.

keys = client.api_keys.list()                              # active org
keys = client.api_keys.list(organization_id="org-uuid")    # explicit org
for k in keys:
    print(k.name, k.role, k.key_prefix, k.last_used_at)

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

Returns list[ApiKey].

create

Issue a new key. The full secret is returned only on this call — persist it immediately. Requires admin or owner role.

Arg	Type	Default	Notes
organization_id	str	required	Target organization UUID
name	str	required	Human label (1-100 chars), not unique
role	ApiKeyRole	"member"	"viewer" / "member" / "admin" / "owner"
rate_limit	int | None	None	Requests/hour cap; defaults to the org’s tier limit
expires_at	datetime | str | None	None	ISO 8601 or None for no expiry

created = client.api_keys.create(
    organization_id="org-uuid",
    name="ci-pipeline",
    role="member",                # viewer / member / admin / owner
    expires_at=None,              # ISO datetime or None for no expiry
)
print("Save this — it is shown once:", created.full_key)

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 — key_id, name, role, key_prefix, and the full key (the only call that returns it).

get

Fetch metadata for a single key (no secret returned).

key = client.api_keys.get("key-uuid")
print(key.role, key.created_at, key.last_used_at)

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

Returns ApiKey.

update

Patch a key’s name, rate_limit, or is_active status. At least one field must be provided. A key’s role is immutable — to change a role, create a new key and delete the old one. Requires admin or owner role.

Arg	Type	Default	Notes
name	str | None	None	New label (1-100 chars)
rate_limit	int | None	None	New requests/hour cap
is_active	bool | None	None	Set False to disable without deleting

client.api_keys.update("key-uuid", name="renamed", rate_limit=10000)
client.api_keys.update("key-uuid", is_active=False)

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

Returns the updated ApiKey.

delete

Revokes the key permanently. In-flight requests using the key fail with 401 AuthError after revocation propagates (≤ 1 second). Cannot be undone.

client.api_keys.delete("key-uuid")

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

Role hierarchy

Keys can only manage keys of equal or lower role. An admin key cannot create an owner key. Owner-tier ops require an owner key.

Caller role	Can create
viewer	nothing — these endpoints all require admin+
member	nothing
admin	viewer, member, admin
owner	viewer, member, admin, owner

Web app vs SDK

• Web app (app.pictograph.io → Settings → API Keys) — visual UI, the most common path for one-off keys.
• SDK / CLI — for programmatic key issuance (CI provisioning, multi-org tools, automated rotation).

The SDK enforces the same role hierarchy as the web UI.

Common errors

Status	Exception	Cause
403	ForbiddenError	Caller’s role too low for the requested action
404	NotFoundError	key_id doesn’t exist or belongs to another org
422	ValidationError	Invalid role string, malformed expires_at