Authentication

Every request must carry a valid Clarifo API key. New keys are 57 characters long: a mode prefix, clf_live_ or clf_test_, followed by 48 hex characters. Keys issued before mode prefixes existed start with a bare clf_ (52 characters) and keep working.

Sending the key

Send the key as a bearer token in the Authorization header:

Authorization: Bearer clf_live_xxxxxxxx…

This is the only accepted way to send the key; a request without it is rejected with 401.

Managing keys

Keys are created from the Clarifo web app under Settings → API keys. Each user can hold up to 5 active keys.

• The raw key value is shown only once, at the moment of creation. Save it immediately.
• Revoked keys stop working on the next request and cannot be reactivated — create a new one instead.
• Each key is either live (clf_live_…) or test (clf_test_…). Both modes reach the same endpoints and the same data. All of your keys share one account-level monthly quota (10,000 requests on Pro); a test key additionally stops at 1,000 requests a month of its own. See Rate limits.

What gets verified

On every call we check, in order:

1. An Authorization: Bearer … header is present — otherwise 401.
2. The key exists, is active (not revoked) and has not expired (if an expiry was set when issued) — otherwise 401.
3. The key's owner has an active plan or trial that includes API access — otherwise 402.
4. The account is within its rate limit — otherwise 429 with Retry-After.
5. The account is within its monthly quota (and a test key within its own cap) — otherwise 429 with X-Clarifo-Quota-Used and X-Clarifo-Quota-Limit.

None of these rejections count against your quota. Error bodies are described on Errors.

Subscription gating

API access is bundled with the Pro and Enterprise plans, and with the 7-day Pro trial; Standard does not include it. Team plans and Team seats include it too. Two places check this:

• Creating and managing keys. The Settings → API keys page needs a qualifying plan. Access is self-serve: subscribe and create a key, no application needed. Without a qualifying plan, key-management calls return 403.
• Using a key. Every API request re-checks that the key's owner still has a qualifying plan or trial. If the subscription has lapsed, requests return 402 until it is renewed; the key itself stays valid.

Upgrade at clarifo.com/pricing.

Example

curl https://api.clarifo.com/api/v1/data/filings/search \
  -H "Authorization: Bearer $CLARIFO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company": "Neste", "limit": 1}'