Authentication

Two ways to authenticate

Every request to /api/v1/ must be authenticated. PIE accepts two credential types, and both resolve to the same organisation-scoped principal on the server:

• API keys — long-lived, machine-to-machine credentials sent in the X-API-Key header. Best for server integrations.
• JWT bearer tokens — short-lived tokens obtained from a login, sent in the Authorization header. Best for interactive sessions.

API keys

Create a key from the API Keys page in your producer (PIP) or buyer (PIC) portal. The secret is shown once at creation — store it securely; PIE only ever keeps a SHA-256 hash and can never show it again. Send it on every request:

curl https://api.example.com/api/v1/products \
  -H "X-API-Key: pie_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Keys carry scopes (for example products:read, products:write) that grant coarse read/write access, and can be marked sandbox (read-only — see below). Rotate a key to mint a replacement while the old one keeps working through a short grace window, then revoke to invalidate immediately.

Sandbox keys

A sandbox key reads your organisation's real data but rejects every mutating request with 403 SANDBOX_READONLY. Every response to a sandbox key carries an X-PIE-Sandbox: true header. Use one to explore the API — including the Try it runner in the API Reference — with zero risk of changing production data.

JWT bearer tokens

Exchange credentials at POST /api/v1/auth/login for a short-lived access token, then send it as a bearer token:

curl https://api.example.com/api/v1/products \
  -H "Authorization: Bearer eyJhbGciOi..."

Access tokens expire quickly; use POST /api/v1/auth/refresh to obtain a new one from the refresh cookie. Unlike API keys, bearer principals are not scope-gated — their access is governed entirely by the signed-in user's role.