This page covers authenticating raw API requests. For a broader overview of keys, rotation, and the dashboard, see Authentication.
Authentication
Authenticate raw API requests with a secret key in the Authorization header: the bearer token format and which key type each call requires.
Every request to the CashSDK API must include a bearer token in the
Authorization header. Server-side calls use a secret key.
bash
Authorization: Bearer csk_sk_live_...
Key types#
| Key | Prefix | Where it's used | Access |
|---|---|---|---|
| Secret key | csk_sk_live_… / csk_sk_test_… | Your backend, CLI, MCP server | Full server-side access |
| Restricted key | csk_rk_live_… / csk_rk_test_… | Your backend, vendor integrations | Only the resources its scopes grant |
| Publishable key | csk_pk_… | Client SDKs | Fetch offerings, start purchases |
| User-token secret | csk_uts_… | Your backend (signing only) | Signs X-CashSDK-User-Token |
| Setup token | csk_st_… | Onboarding & provisioning | Scoped, short-lived setup tasks |
Only the keys that run on your server carry a mode. The credentials that ship
inside your app do not: one csk_pk_… and one csk_uts_… per app, working in
every store environment, because TestFlight and the App Store run the same binary
with different purchase environments. See
Authentication.
Never embed a secret key in a mobile or web client. Client apps authenticate with a publishable key only. If a secret key leaks, rotate it immediately from Settings → API keys.
Test and live keys#
Each key carries its mode. A csk_sk_test_… reads Sandbox data and a
csk_sk_live_… reads Production data, and neither can reach the other. Asking
for the other environment with ?environment= or X-CashSDK-Environment returns
400 environment_mismatch.
The store still decides which environment a purchase belongs to (a build run from Xcode or TestFlight transacts against Apple's sandbox). CashSDK reads that from the store's own signed payload, so a client cannot spoof it, and entitlements are resolved per environment so a Sandbox purchase never grants Production access.
Keys issued before modes existed (csk_sk_3DXP…, no test/live segment) still
work and still resolve the environment from your app's default setting. See
Testing.
Example request#
bash
curl https://api.cashsdk.com/v1/apps \
-H "Authorization: Bearer csk_sk_..."
json
{
"data": [
{
"id": "app_2mK4pQ",
"name": "Focus Timer",
"platform": "ios",
"bundle_id": "com.example.focustimer",
"created_at": "2026-05-02T09:14:00Z"
}
],
"has_more": false,
"next_cursor": null
}
Failed authentication#
A missing, malformed, or revoked token returns 401 Unauthorized:
json
{
"error": {
"code": "unauthorized",
"message": "No valid API key was provided."
}
}
Using a key without permission for a resource returns 403 Forbidden. See
Errors for the complete list.