Every Clarion API request is authenticated with a company-scoped API key, except a push URL, which carries its own credential. If you don’t have a key yet, see Create API keys.
Base URL
https://api.onclarion.com/v1All paths below are relative to it. :companyId is your company’s id, shown in the Company ID field under Settings → Integrations → API Keys.
Send the key
Use either header — they’re equivalent:
curl "https://api.onclarion.com/v1/companies/$COMPANY_ID/metrics" \
-H "x-api-key: clr_YOUR_KEY"curl "https://api.onclarion.com/v1/companies/$COMPANY_ID/metrics" \
-H "Authorization: Bearer clr_YOUR_KEY"Two checks happen on every request:
- The company must match. A key belongs to exactly one company. If
:companyIdin the path is a different company, the request is refused — including a client company’s key trying to reach its parent agency’s data. - The key must hold the endpoint’s scope.
Scopes
| Scope | Grants | Endpoint |
|---|---|---|
metrics:write | Write metric values | POST /companies/:companyId/metrics/ingest |
metrics:read | Read metrics | GET /companies/:companyId/metrics |
milestones:read | Read milestones | GET /companies/:companyId/milestones |
action_items:read | Read action items | GET /companies/:companyId/action-items |
Clarion only issues scopes that have an endpoint behind them. Give each integration the fewest scopes that let it work: a script that pushes revenue needs metrics:write and nothing else.
Errors
Errors come back as JSON with a statusCode and a human-readable message (plus a timestamp and the request path):
{
"statusCode": 403,
"message": "API key missing required scope(s): metrics:read"
}| Status | Meaning | What to do |
|---|---|---|
401 | No key sent, or the key is wrong or revoked. Messages: API key required (x-api-key header), Invalid or revoked API key | Check the header name and the key. If it was revoked, create a new one. |
403 | The key belongs to another company (API key does not have access to this company), or lacks a scope (the message names it) | Check the company id in the path, or create a key with the right scopes. |
400 | The request body is malformed — for example, ingest without a non-empty entries array | Fix the body. |
404 | For push URLs: the URL is unknown, replaced, turned off, or its metric archived | Generate a new push URL. |
A 201 from ingest doesn’t mean every value was written. Check each entry’s status in the response — see Ingest metric values with the API.
Versioning
The version is in the path. Within v1, Clarion adds endpoints, optional request fields and response fields, but doesn’t remove or rename fields, change their types, or change what an existing request does. Treat unknown response fields as normal and ignore them. Older unversioned paths under https://api.onclarion.com/api/... still answer but carry no compatibility promise; use /v1.
Keep keys safe
Keys never expire, so treat them like passwords: keep them in a secrets store, never in front-end code or a public repository, and revoke any you stop using. An embedded app that needs Clarion data should call the API from its backend, never from the browser.