---
title: Authentication
description: API key format, resolution order, and the role-based permission model.
section: Get Started
order: 2
---
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](https://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:

```bash
export PICTOGRAPH_API_KEY=pk_live_…
```

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

Or pass it explicitly:

```python
client = Client(api_key="pk_live_…")
```

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

```bash
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

```bash
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`](/docs/api-reference/tools.md).

## 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](/docs/rate-limits.md)) |