New France e-invoicing mandate goes live September 2026 — our implementation is ready. See all mandates →
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.

What next