Authentication
Requests are authenticated with a secret API key sent as a bearer token on every call.
The Authorization header
Include your API key as a bearer token. Sandbox keys use the chsk_test_ prefix, production keys use chsk_live_.
curl "https://api.crisphive.com/v1/customers" \ -H "Authorization: Bearer chsk_test_4eC8xQ9mZ2pL7Ka0rT"
Managing keys
Create keys under Settings → Developers — name the key, copy the value once at creation, restrict it to specific permission scopes if you like, and revoke it any time.
A key can never carry more than its creator: scopes on a new key are capped by the permissions of the user creating it, even if the scope list is left empty. If a creation requests more, it fails with 403 API_KEY_SCOPE_NOT_GRANTED — have a user with full access (or an Owner) create the key if you need the full surface.
Expiry
API keys expire. You choose a key’s lifetime when you create it — 30 days by default, from 1 up to 365 — and it is fixed for the life of that key. A lifetime cannot be extended later (renaming a key never changes it), so expires_at on a key never moves. It is returned by the key API and shown in the dashboard; read it and schedule the changeover.
Crisphive also emails the business’s Owners and Administrators 7 days before a key expires, and again once it has. Don’t rely on the email alone — it goes to the business, not necessarily to you; keep reading expires_at and schedule the changeover yourself.
Renewing a key
To renew, create a new key — there is no rotate endpoint. A business can hold up to 50 active keys per environment, so the handover needs no special machinery and has no downtime:
Create the replacement key in the dashboard.
Deploy the new key to your integration.
Confirm traffic is flowing on the new key (last_used_at, or Developers → Logs).
Revoke the old key from the dashboard.
This is the same two-key procedure AWS documents for access keys. Load the key from configuration, never hardcode it, so step 2 is a config change rather than a release. For a leaked key, do it in the other order — revoke first, then create the replacement; a few failed calls beat leaving a compromised key alive. Key management is dashboard-only — there is no public API to mint or revoke keys.
401 with error_code: "API_KEY_EXPIRED" — deliberately distinct from API_KEY_INVALID (revoked, deleted, or wrong), so your alerting can tell a missed renewal apart from a revocation.Acting on behalf of other businesses
API keys authenticate your own business. Building a product that other Crisphive businesses connect to? Use OAuth 2.1 instead — each business owner authorizes your app on a consent screen, and no key is ever shared.