Getting Started
Authentication
Every request to the Clearvo API requires an API key passed in the x-api-key header. Keys are scoped to either one entity or an entire organisation (with a per-request X-Entity-Id header) — see API keys.
| Header | Type | Description |
|---|---|---|
| x-api-key | string | Your API key. Required on every request. |
| x-idempotency-key | string (UUID) | Required on all POST requests. Replaying the same key within 24 h returns the cached response without re-submitting. See Idempotency. Required on POST |
| x-entity-id | string (UUID) | Required when using an organisation-scoped key (omit entirely for an entity-scoped key, which resolves its one entity automatically). Must be one of the organisation's entities — or one of the key's allowed entities, if it's restricted to a subset. Required for org-scoped keys |
Never expose your API key in client-side code or public repositories. Use environment variables. Test keys begin with
csk_test_ and are created in Sandbox mode (Enterprise plan); live keys begin with csk_live_ and are created in live mode.
HTTP
x-api-key: csk_live_••••••••••••
x-idempotency-key: a3f9c2d1-e847-4b6a-9c12-d3f0e1a2b7c8
Content-Type: application/json
Your first request
Check that your key works by listing your entities. This is a read-only call, so it needs no idempotency key:
cURL
curl https://api.clearvo.io/v1/entities \
-H "x-api-key: csk_test_••••••••••••"
A 200 with your entities means you are ready. A 401 means the key is missing, mistyped or revoked.