Skip to main content
How PIK API authentication works, the difference between sandbox and production credentials, and how to keep your keys secure.
Every request to the PIK API must be authenticated using an API key. Your API key identifies your platform and authorises PIK to process requests on your behalf. Keep your API keys secure — treat them like passwords.

​
API keys

PIK uses bearer token authentication. Include your API key in the Authorization header of every request. Authorization: Bearer YOUR_API_KEY API keys are scoped to your platform account. There are two types: Production key — Used for live transactions that move real funds. Generated from the PIK Dashboard under Settings > API Keys > Production. Sandbox key — Used for testing. Transactions made with a sandbox key are simulated and never move real funds. Generated from the PIK Dashboard under Settings > API Keys > Sandbox. Never use your production key in a test environment. Never use your sandbox key in production. Keep both keys out of client-side code, public repositories, and logs.

​
Acting on behalf of connected accounts

When your platform makes API calls on behalf of a specific connected account, include the x-on-behalf-of header alongside your Authorization header. Authorization: Bearer YOUR_PLATFORM_API_KEY x-on-behalf-of: CONNECTED_ACCOUNT_ID Without x-on-behalf-of, the request is scoped to your platform account. With it, the request is scoped to the specified connected account — using that account’s wallet balance and permissions.

​
Key rotation

PIK supports multiple active API keys simultaneously. To rotate a key without downtime: Step 1 — Generate a new key in the PIK Dashboard. Step 2 — Update your application to use the new key. Step 3 — Verify requests are succeeding with the new key. Step 4 — Delete the old key from the PIK Dashboard.

​
Permissions

API keys inherit the permissions of the platform account they belong to. If a connected account does not have a capability activated, API calls attempting to use that capability will return a 403 error regardless of your API key.

​
Authentication errors

401 Unauthorized — Your API key is missing, invalid, or has been deleted. Check that the Authorization header is correctly formatted and the key is active. 403 Forbidden — Your key is valid but does not have permission to perform the requested action. This may mean the connected account capability is not activated, or the account is not yet verified.