Account & Platform

Authentication, entity management, and API keys work identically across every Clearvo product — E-Invoicing, Tax Calculations, Tax Number Validation, Compliance Radar, and Real-Time Reporting all share one key system and one entity model. This page is the single source of truth for all of it; each product's own docs link back here instead of repeating it.

Account & Platform

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 below.

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_; live keys begin with csk_live_.

HTTP

x-api-key: csk_live_••••••••••••
x-idempotency-key: a3f9c2d1-e847-4b6a-9c12-d3f0e1a2b7c8
Content-Type: application/json

Account & Platform

Entities

Entities represent the legal entities in your organisation that are registered for tax compliance. Each entity has its own tax numbers, credentials, and compliance footprint. All transactional API calls — e-invoicing, tax calculations, tax number validation — are scoped to an entity.

Method	Path	Description
`GET`	`/v1/entities`	List all entities in your organisation
`POST`	`/v1/entities`	Create a new entity
`GET`	`/v1/entities/:id`	Retrieve a single entity
`PATCH`	`/v1/entities/:id`	Update entity name, address, or VAT number

ℹ

Entity management endpoints require an API key with products: ["entities"] scope and account level access (not entity-scoped).

Account & Platform

API Keys

API keys authenticate every request to the Clearvo API. Keys are scoped to either an account (with a required X-Entity-Id header per-request) or a specific entity. An account-scoped key can optionally be restricted to a chosen subset of your entities — X-Entity-Id is still required on every request either way; the restriction only limits which entities it's allowed to name. You can also restrict a key to specific products (einvoicing, tax, tin, entities) and access levels (read or write).

Keys are created and managed from the dashboard (Developers → API Keys) — there is no public API endpoint for creating, listing, or revoking keys, so revocation always takes effect immediately with nothing to cache.

Key fields

Field	Values	Description
`scope`	`entity` \| `account`	Entity-scoped keys are tied to one entity. Account-scoped keys work across entities with `X-Entity-Id` — optionally restricted to a chosen subset of entities instead of all of them.
`access`	`write` \| `read`	Read-only keys return 403 on write operations.
`products`	`["all"]` or subset	Restrict to `einvoicing`, `tax`, `tin`, or `entities`. Default: `["all"]`.
`prefix`	`csk_live_` \| `csk_test_`	Live vs. sandbox environment. Set at creation; cannot be changed.