API keys & secrets
How keys authenticate the SDK, when to use signed requests, and what never to ship in a client binary.
The public API uses Authorization: Bearer <key>. Two kinds of secrets exist in the dashboard, and only one is safe to embed in an app.
Publishable key
- Client-safe. Ship it in your binary.
- Scoped to one app and one environment.
- The value is opaque; treat it as public.
Signing secret
- Server-only. Never ship it in mobile or browser code.
- Enables HMAC-signed requests via the
X-CtrlApp-Signatureheader. - Read Authentication for the exact signature format.
If a secret leaks, rotate
DashboardApps → API keys → rotate
Roll the key and update every consumer. The old key is invalidated.Common mistakes
- If your mobile app is signing requests — disable signing on client SDKs — the secret is not safe there.
- If curl returns
401— the header must literally beAuthorization: Bearer <key>, no extra quotes.