Authentication
Every API call is authenticated with a workspace-scoped API key sent in the X-API-Key header. Keys carry scopes and are bound to one environment.
The X-API-Key header
Send your API key in the X-API-Key header on every request. There is no session, no cookie, and no unauthenticated endpoint other than the status page.
X-API-Key: idpf_live_9f2a4c81e6b74d0fa3c5e7b921d84f60Key format
A key is idpf_<environment>_<random>. The environment is baked into the key, so a key only ever acts in the environment it was minted for, and a job inherits its environment from the key that submitted it.
| Prefix | Environment | Notes |
|---|---|---|
idpf_sandbox_ | Sandbox | Free, rate-limited. Never bills against your plan. |
idpf_live_ | Production | Metered against your plan allowance. |
Only a SHA-256 hash of the key is stored — the full secret is shown once, at creation. To mint one, see Generate an API key.
Scopes
A key is minted with a set of scopes. Scopes describe the access a key is intended for; the key's plan and bound pipeline also govern what it can reach, and per-scope enforcement is tightening over time.
| Scope | Grants |
|---|---|
jobs:write | Submit and cancel jobs |
jobs:read | Read job status, stage traces, and results |
pipeline:read | List pipelines and their published versions |
api-keys:manage | Create, rotate, and revoke API keys |
billing:read | Read credit balance and billing |
The full secret is returned only in the create response. Store it in your secret manager immediately. Rotating issues a new secret with an overlap window, so callers migrate without downtime.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_api_key | Missing, malformed, revoked or expired key. |
403 | insufficient_scope | Valid key, but the scope was not granted. |
404 | not_found | Resource exists but is outside the key's workspace — deliberately indistinguishable from absence. |
429 | rate_limited | Back off using the Retry-After header. |