Authentication

The Developer API authenticates via API keys — pk_live_… strings issued from Settings → API Keys in the web app. The same key works for the SDK, the pictograph CLI, and direct REST calls.

Get an API key

1. Sign in at app.pictograph.io.
2. Settings → API Keys → Create API Key.
3. Pick a role: viewer / member / admin / owner (see below).
4. Copy the key — shown once, never again.

Use the key

The SDK reads PICTOGRAPH_API_KEY from the environment by default:

export PICTOGRAPH_API_KEY=pk_live_…

from pictograph import Client
client = Client()  # uses env var

Or pass it explicitly:

client = Client(api_key="pk_live_…")

The CLI has the same resolution order plus a ~/.pictograph/config.toml file written by pictograph login:

pictograph login            # prompts (input hidden), writes ~/.pictograph/config.toml
pictograph datasets list    # uses the saved key

Resolution order

Priority	Source
1 (highest)	--api-key flag (CLI) or Client(api_key=...) arg (SDK)
2	PICTOGRAPH_API_KEY environment variable
3	~/.pictograph/config.toml [default].api_key (CLI only)
4 (failure)	ConfigurationError raised

REST clients

curl -H "X-API-Key: pk_live_…" https://api.pictograph.io/api/v1/developer/datasets/

The header name is exactly X-API-Key. Bearer tokens are not accepted on developer endpoints.

Roles + permissions

API keys carry a role that the backend re-enforces server-side. Roles are hierarchical: owner > admin > member > viewer.

Role	Read	Create / update	Delete	Invite users	Org settings
viewer	✓	—	—	—	—
member	✓	✓	own resources only	—	—
admin	✓	✓	✓	✓	—
owner	✓	✓	✓	✓	✓

The agent tool registry tags each tool with required_role — see /docs/api-reference/tools.

Key format

API keys look like pk_live_<32_random_bytes_base64>. They are bcrypt- hashed server-side (cost factor 12) and stored only as the hash plus the first 12 chars (pk_live_<8>) for the prefix-lookup index. Once created, the full key is never recoverable.

Rotation

To rotate:

1. Settings → API Keys → Create API Key (new key).
2. Update PICTOGRAPH_API_KEY / ~/.pictograph/config.toml / your CI secret.
3. Delete the old key once the rollout is verified.

There is no in-place rotation — every key is immutable after creation.

Errors

Status	Exception	Cause
401	AuthError	Missing / malformed / unknown / revoked key
403	ForbiddenError	Key’s role lacks permission for the operation
429	RateLimitError	Per-key rate cap hit (see Rate limits)