API keys & scopes
API keys authenticate your servers when they call the CustomerHero REST API. Every key is scoped to a single organization and to a specific set of permissions.
Creating a key
Go to Settings → API keys → New key. Give the key a descriptive name (e.g. "Production backend", "Staging worker"), pick the scopes it needs, and copy the secret. The secret is only shown once — store it in your secret manager immediately.
Keys are formatted sk_live_…. Send them as a Bearer token on every request:
curl https://us.api.customerhero.app/api/orgs/ORG_ID/chatbots \
-H "Authorization: Bearer sk_live_your_api_key_here"Scopes
Scopes are verb-first and grouped by resource. Pick the narrowest set that lets your integration do its job — never grant admin:* or * to a key that only needs to read customer records.
| Scope | Grants |
|---|---|
| chat:write | Send messages to a chatbot from a server (the public chat endpoint). |
| inbox:read | List and read conversations, messages, and assignments. |
| inbox:write | Reply, change status, assign, tag, and add internal notes. |
| customers:read | List and read customer and company records. |
| customers:write | Create, update, merge, and delete customers and companies. |
| chatbots:read | List chatbots and read their configuration. |
| chatbots:write | Create, update, and delete chatbots, data sources, and actions. |
| billing:read | Read plan, usage, credit balance, and invoices. |
| admin:* | Org-wide admin operations: members, roles, SSO, webhooks. Use sparingly. |
| * | Everything. Avoid in production. |
A trailing :* grants every action in that group — e.g. chatbots:* covers both chatbots:read and chatbots:write. A request with insufficient scope gets HTTP 403 with {"error":"Missing scope: ..."}.
Rotation
Rotate keys at least every 90 days, and immediately if a key may have leaked. The safe pattern is two-step:
- Create a new key with the same scopes, deploy it to your servers, and verify traffic on the new key.
- Revoke the old key. Revocation is immediate — in-flight requests on the old key get HTTP
401on their next call.
Each key has a last used at timestamp on the settings page so you can confirm the new key is taking traffic before you revoke the old one.
Security best practices
- Server-side only. Never embed an API key in a browser, mobile app, or public repo. The widget script does not need an API key — it uses public per-chatbot endpoints.
- One key per service. Separate keys for each backend service, plus separate keys for staging and production. That way revoking one doesn't take down unrelated workloads.
- Restrict by IP where possible. On Business and Enterprise plans, restrict keys to a CIDR allowlist under the key's settings.
- Audit log. Every key creation, scope change, and revocation is recorded in the org audit log. Review it after onboarding/offboarding.
Next steps
Start calling the API in the API reference, or subscribe to outbound webhook events.