API Keys

API keys let your other software sign in to Clorvia as an integration instead of as a person. Each key is bound to a role, so it can only do what that role is allowed to do, and you can revoke it at any time.

Create an API key

1. Go to Settings → APIs & Webhooks.
2. Under API keys, click Create API key.
3. Give it a clear name (e.g. “Website checkout”, “Accounting sync”).
4. Choose the role the key should act as — this controls its permissions.
5. Optionally set an expiry date.
6. Click Create, then Generate token.

Copy the token now. The full token is shown only once, right after you generate it. Store it somewhere safe (a secrets manager). If you lose it, just revoke the key and generate a new one — you can’t view it again.

Use the token

Send it as a Bearer token on every request:

Authorization: Bearer YOUR_API_KEY_TOKEN

See Using the API for full examples.

Scope a key with roles

A key inherits the full permissions of the role you assign it. Best practice:

• Create a dedicated role for each integration with only the permissions it needs (for example, a read‑only role for a reporting tool).
• Use separate keys for separate systems, so you can revoke one without affecting the others.

You can reassign a key to a different role later from the same screen.

Expiry and rotation

• An optional expiry date means the key stops working automatically after that date — useful for temporary access.
• To rotate a key, create a new one, switch your integration over, then revoke the old one.

Revoke a key

If a key is no longer needed or may have leaked, click Revoke. Revocation is immediate — the very next request with that token is rejected. Revoking is permanent; there’s no “un‑revoke” (create a new key instead).

Keep keys safe

• Never put a key in client‑side code, a public repository, or a URL.
• Treat a key like a password — anyone with it can act as that role in your workspace.
• Rotate keys periodically and whenever a team member with access leaves.