How to create and revoke Clarion API keys

An API key lets a script, pipeline or automation platform call the Clarion REST API without a user signing in. Each key belongs to one company and carries only the scopes you choose.

You need to be an owner or admin of the company to manage keys. See Roles and permissions.

Create a key

1. Make sure you’re working in the company the key is for. A key only ever works for the company it was created in.
2. Go to Settings → Integrations and scroll to API Keys. The badge beside the heading confirms which company you’re in.
3. Copy the Company ID from the field at the top of the card. Every API path includes it.
4. Type a name in Key name that says what will use it — “Shopify metrics sync”, “Weekly digest bot”. You’ll be glad of it when deciding what to revoke.
5. Under Scopes, tick only what the integration needs:
   • metrics:read — Read metrics
   • metrics:write — Write metrics (ingest)
   • action_items:read — Read action items
   • milestones:read — Read milestones
6. Click Create Key.
7. Copy the key from the green box and store it in your secrets manager or your tool’s credential store. It looks like clr_ followed by 48 characters. It won’t be shown again — Clarion keeps only a hash.
8. Click Done.

Check a key

Active keys are listed under the form with their name, the first characters of the key (for example clr_3f9a1c0b…), the date they were created, when they were last used, and their scopes. “Last used” updates on every successful request, which is the quickest way to tell whether an integration is still running.

Change a key’s scopes

Scopes can’t be edited after creation. Create a new key with the scopes you want, switch the integration over, then revoke the old key.

Revoke a key

1. In API Keys, find the key and click Revoke.
2. Confirm. Anything using the key fails with 401 Unauthorized on its next request.

Revoked keys disappear from the list. Keys don’t expire on their own, so revoke any you no longer use, and revoke immediately if a key may have leaked.

Next steps

• API authentication and scopes — how to send the key and what each error means.
• Ingest metric values with the API — write numbers into the scorecard.
• Read data with the API — list metrics, milestones and action items.

If a tool can’t send headers at all, it can’t use an API key. Give it a push URL instead.