Proxy Charm

Authentication

The API uses bearer API keys. There is no OAuth flow, no signing, and no separate token exchange.

Send your key on every request. There is no session, so nothing is remembered between calls.

Request header 
Authorization: Bearer px_live_YOUR_KEY

What a key can reach

A key is scoped to one organization. Every request is silently filtered to that organization's data — there is no cross-organization read, and you never need to pass an organization id.

  • Keys are organization-level, not per-person. Anyone with the key acts as the organization.
  • There are no per-endpoint scopes yet. A valid key can call all eight endpoints.
  • GET /invoices additionally requires that the key was created by an organization owner. Keys made by an admin get ORGANIZATION_PERMISSION_DENIED there.

Key lifecycle

Keys are created and revoked from the dashboard, never from the API. That keeps a stolen key from minting more keys.

Creation The plaintext value is returned exactly once. We store a SHA-256 hash, so a database leak does not expose usable keys.
Prefix Every key starts with px_live_. The dashboard lists keys by that prefix and a short suffix so you can tell them apart without seeing the secret.
Expiry Optional, and fixed at creation. An expired key returns API_KEY_EXPIRED and cannot be extended — create a new one.
Revocation Immediate. The next request with that key returns API_KEY_REVOKED.
Last used Recorded on each successful request, so you can spot a key that nothing depends on before you revoke it.

Rotating a key

There is no automatic rotation, so overlap the old and new keys rather than cutting over:

  1. Create a second key with a label naming the service that will use it.

  2. Deploy the new value to that service.

  3. Watch the last-used column on the Developer page until the old key stops moving.

  4. Revoke the old key.

Authentication failures

All of these arrive as real HTTP error statuses, with the code under detail.code rather than error.code. That differs from business failures — see the conventions page.

Code HTTP What it means
API_KEY_INVALID 401 The Authorization header is missing the key prefix, the key does not exist, or its organization has been deleted.
API_KEY_REVOKED 401 The key was revoked in the dashboard.
API_KEY_EXPIRED 401 The key passed the expiry date it was created with.
NOT_AUTHENTICATED 403 No Authorization header was sent at all.

Storing keys safely

  • Keep keys in environment variables or a secret manager, never in source control.
  • Do not call this API from browser or mobile code. A key shipped to a client is a public key.
  • Give each service its own key so you can revoke one without taking down the rest.
  • Revoke immediately if a key appears in a log, a screenshot, or a pull request.