API Authentication
Scoped keys, shown once.
Bearer-token authentication with per-key scopes, separate environments, IP restrictions and rotation without downtime.
ScopedRotatableIP restrictable
How does ChainwatchCrypto API authentication work?
The ChainwatchCrypto API uses scoped keys, shown once at creation and never retrievable afterwards. Each key carries only the permissions granted to it, and the recommended practice is the narrowest scope that works. Keys rotate and revoke independently, so a compromised key does not require rebuilding an integration.
Keys
How a key behaves.
| Property | Behaviour | Why |
|---|---|---|
| Prefix | cw_live_ or cw_test_ | The environment is visible in the key itself, so a test key in production config is obvious. |
| Display | Secret shown once at creation | We store a hash. If you lose the secret, rotate; we cannot retrieve it. |
| Scopes | Per-key, least privilege | A monitoring integration should not hold a key that can read cases. |
| IP restriction | Optional allowlist per key | Where your integration has stable egress addresses, use it. |
| Rotation | Overlapping validity window | Create the new key, deploy it, then revoke the old one. No downtime. |
| Revocation | Immediate | A revoked key fails on the next request, not at the next cache expiry. |
Scopes
Grant the narrowest set that works.
| Scope | Grants |
|---|---|
| wallets:read | Wallet profiles and transfers. |
| transactions:read | Normalised transaction detail. |
| risk:check | Score addresses and transactions. |
| monitoring:read | List monitored addresses and rules. |
| monitoring:write | Create, modify and remove monitoring rules. |
| alerts:read | Read alerts raised for your organisation. |
| cases:read | Read case state and report metadata. |
| cases:write | Create cases and submit evidence. |
| entities:read | Entity profiles and attributions. |
| screening:check | Sanctions and designation screening. |
Handling secrets
Four rules worth stating.
Store keys in environment configuration, never in source control
Never place a key in client-side code — a browser cannot hold a secret
Use separate keys per service so one compromise does not require rotating everything
Rotate on a schedule as well as on incident
If a key is exposed
Revoke it immediately from the dashboard, then create a replacement. Revocation takes effect on the next request. Every key creation, rotation and revocation is written to the audit log with the actor who performed it.
Related pages