Authentication and API Keys
What an API key is
An API key is the secret your code sends to Cognivo so we know a request is yours. Every Developer API call carries one. Keys sit inside a project, and a project groups your keys and their usage together.
Read this page before your first call, when you need to know what a key is allowed to do, or when a key may have leaked and you need it switched off.
Where to find it
Sign in to the Cognivo dApp, open Account in the left sidebar, then Developers. Signed out, the page shows an orientation screen only.
The Developers page has four tabs: Keys, Usage, Endpoints and Quickstart. Everything on this page happens on the Keys tab.
Live access and your credit balance
A banner at the top of the page states the access model plainly: some endpoints are free with any active key, and others are charged per successful call from your Cognivo credit balance. Further down, the Live API access card confirms that a live key works the moment you create it. There is no approval step and no waiting list.
Beside it the page shows your current credit balance, a Top up credits button, and an Enterprise access button. Enterprise is the only access path that goes through a request, for custom pricing or higher limits. Everything else is self serve.
Every Cognivo account also receives 5 free credits each day, which reset at midnight UTC. See Billing and credits for how the balance works, and Rate limits, errors and billing for the per-endpoint prices.
The Keys tab
Pick a project from the Project dropdown, or create one with New project. The Keys tab then lists every key that belongs to it.
Each key row shows the name you gave it, whether it is a Test or Live key, the hourly limit that applies, the permissions it carries, and when it was created and last used. Last used: Never means no call has ever been made with that key.
Only the prefix and the last four characters of a key are shown. Cognivo stores nothing else that can be read back, which is why the full key appears exactly once.
Creating a key
Select + New key. The form asks for three things: an optional name to help you tell your keys apart, a mode of Test or Live, and at least one permission.
Choosing Live shows your credit balance under the mode dropdown, as a reminder that live calls are real calls and are charged from that balance. Choosing Test creates a sandbox key that is never charged and has tight limits.
Select Create key and the full key appears once, in a dialog.
- Use the copy icon to copy the full key while it is still on screen, as it is not shown again.
- Select Done once the key is stored somewhere you can find it later.
If you lose the key, you cannot recover it. Rotate the key instead, which is covered below.
Sending your key
The canonical header is X-API-Key:
curl -X POST 'https://api.cognivolabs.io/v1/api/intel/risk' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"chain":"eth","address":"0xTOKEN_CONTRACT"}'
Authorization: Bearer YOUR_API_KEY is accepted as an alias for client libraries that prefer it. Keep the key on your server. Never put it in browser code.
The API covers Ethereum, Base and BNB Chain today.
Permissions
Keys are default deny. A key can only call the endpoint groups you granted when you created it. There are three permissions, and each one unlocks a set of endpoints.
Intelligence (intel:read) is the everyday permission. It answers "what is going on with this token or wallet?": price-drop drivers, risk signals, team wallet behaviour, realised PnL and exact movements. It unlocks POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl and POST /v1/api/wallet/exact-movements.
Security (security:read) lets a key check what a wallet has approved, including which contracts can spend its tokens and which allowances are unlimited. It is read only. A key with this permission can never move funds or revoke an approval. It unlocks POST /v1/api/wallet/approvals.
Liquidity (liquidity:read) lets a key read pool context, LP custody, and lock and burn context. It unlocks POST /v1/api/intel/liquidity.
GET /v1/api/health needs no key at all. GET /v1/api/me and GET /v1/api/discover work with any valid key, whatever its permissions.
Permissions are fixed when the key is created. To change them, create a new key with the permissions you need and revoke the old one. A call that fails with 403 scope_denied means the key does not carry the permission that endpoint needs.
Test keys and live keys
| Prefix | What it is for | Billing | Rate cap |
|---|---|---|---|
cogv_test_ | Trying the API out. Labelled Test and Sandbox in the portal. Cannot run live intelligence. | never charged | 25 requests per hour, 100 per day, 1 per second |
cogv_live_ | Real traffic. Self serve, works immediately. | Cognivo credits per successful call. Failed calls are never charged. | 1,000 requests per hour to start, see rate limits |
A test key is not a free production key. Live calls made with one answer 403 sandbox_limited. Charging for Developer API calls is switched off today, so a successful call deducts nothing and your balance does not move.
The portal also shows an access mode on each key. Paid is ordinary pay as you go. Trial is a temporary evaluation allowance with an end date. Partner and Enterprise are arrangements set up with Cognivo. Suspended means the key cannot execute anything, and the portal shows the reason. A small number of older keys predate self-serve billing and can only call the metadata endpoints, so live calls answer 403 access_required. Create a new live key to move those to pay as you go.
GET /v1/api/me reports your key's access mode, its permissions, your credits_balance and top-up guidance. If your balance cannot cover a call you get 402 payment_required and nothing is charged. Top up and retry.
Rotating and revoking
Both controls sit on the right of every key row.
- Read the Test and Sandbox badges next to the name to see what kind of key this is, along with the hourly limit shown beside them.
- Select Rotate to replace this key with a new one, which is shown once and stops the old key working right away.
- Select Revoke to switch a key off for good, for example if it is no longer needed or you think someone else has seen it.
Rotate asks you to confirm first, and the dialog says exactly what will happen.
A rotated key keeps its name, permissions, tier, any network restriction, any expiry date and any remaining allowance, so rotating is safe and never quietly widens what the key can do. The replacement is shown once, in the same dialog as a new key. Revoking is permanent and stops the key working on every endpoint right away.
Rotate on any suspected leak, and on a regular schedule.
Restrictions Cognivo can apply to a key
These are set on the key record rather than in the portal form, and they are enforced on every request. You can confirm what applies to your own key with GET /v1/api/me.
- Network restriction. A key can be limited to specific networks. A request naming a different network is refused with
403 chain_denied. The refusal happens before Cognivo calls anything upstream and before any allowance is used, so a call your key is not permitted to make never costs you anything. Reported asallowed_chains, wherenullmeans no restriction. - Expiry. A key can be given an end date. After it passes, the key stops working everywhere, including
GET /v1/api/me, and returns403 key_expired. Reported asexpires_at, wherenullmeans it does not expire. If a trial allowance also has an end date, whichever comes first applies. - Origin and IP allow lists. A key can be limited to specific origins, including wildcard subdomains such as
https://*.yourapp.com, or to specific IP addresses and CIDR ranges. Requests from anywhere else are refused with403 origin_denied. Empty lists mean no restriction.
Next steps
With a key in hand, make your first call in the Quickstart, then browse the Endpoint reference to see what each endpoint returns and what it costs. If a call comes back with an error code you do not recognise, Rate limits, errors and billing lists every one of them.