Authentication

Bearer API keys — test and live — with scopes, IP allowlists, and spend caps.

Every request authenticates with an API key in the Authorization header:

curl https://sandbox-api.platform.chipper.ai/v1/payouts \
  -H "Authorization: Bearer sk_test_..."

Test and live keys

Prefix	Stack	Behavior
sk_test_…	Sandbox	Simulated rails, testnet chains. Free to hammer.
sk_live_…	Production	Real money. Guard accordingly.

A key only works on its own stack — a sk_test_ key against the production URL is just an invalid key. This makes it impossible to accidentally move real money with test code.

Keys are created in the dashboard under Developers → API keys. The full key is shown once, at creation. We store only a hash — if a key is lost, create a new one, switch your integration, and revoke the old (there is deliberately no “rotate” button; rotation is create → switch → revoke, so both keys work during the switchover).

Scopes

Each key carries scopes — payouts:write, recipients:read, and so on — set at creation. A request with a key that lacks the needed scope fails with 403:

{ "error": "forbidden", "message": "API key does not have the required scope" }

Give integration keys the narrowest scopes that do the job: a reporting service needs payouts:read, not payouts:write.

IP allowlists

A key can be restricted to a list of caller IPs. Requests from any other address fail with 403 even with a valid key. Recommended for production keys running from fixed infrastructure.

Spend caps

Live keys can carry daily / per-transaction / monthly USD caps, enforced across all currencies at current rates. A payout that would exceed a cap is rejected before any money moves.

Caps are how you hand a key to something you don’t fully control — including an AI agent. Give an agent its own key with narrow scopes and a hard budget (say, $50 per transaction,$500 per day), and it can pay suppliers or settle invoices autonomously while the platform guarantees the blast radius: no bug, prompt injection, or runaway loop can spend past the cap.

Failure modes

Status	error	Meaning
401	unauthorized	Missing, malformed, expired, or revoked key.
403	forbidden	Valid key, but missing scope or blocked IP.
403	organization_suspended	The organization is suspended — contact support.

Never ship an API key in client-side code, mobile apps, or repositories. Keys belong on your server.