Authentication

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

The full key is shown at creation. It is stored two ways: a one-way hash, which is what authenticates every request, and a separately-encrypted copy that only the reveal flow can read. So a key created today can be shown to you again from Settings - once per sign-in, restricted to members and above, and every reveal is recorded. Keys issued before that feature existed have no encrypted copy and genuinely cannot be recovered; rotate one to get a key you can view.

Use the key

export PICTOGRAPH_API_KEY=pk_live_...

from pictograph import Client

client = Client()                       # reads the environment
client = Client(api_key="pk_live_...")    # or pass it explicitly

pictograph login            # prompts (input hidden), writes ~/.pictograph/config.toml
curl -H "X-API-Key: $PICTOGRAPH_API_KEY" https://api.pictograph.io/api/v1/developer/datasets/

The header name is exactly X-API-Key. Bearer tokens are not accepted on developer endpoints; the one exception is a deployment’s own pk_deploy_ token, which authenticates that deployment’s /predict URL and nothing else.

Resolution order

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

Roles

A key carries a role, re-enforced server-side on every request. Roles are hierarchical: owner > admin > member > viewer.

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

The agent tool registry tags each tool with required_role - see Tools.

Rotation

Keys are immutable: there is no in-place rotation. Create the new key, update PICTOGRAPH_API_KEY / ~/.pictograph/config.toml / your CI secret, verify, then delete the old one.

Errors

Source: exceptions.py

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