Skip to main content

Authentication and API keys

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.

How keys are stored​

Cognivo never stores your full key. Only a one-way hash plus the prefix and last four characters are kept, which is why the full key can be shown exactly once at creation. Treat it like a password.

Sandbox keys vs live keys​

PrefixPurposeBillingRate cap
cogv_test_Sandbox: limited demos and integration testing only, clearly labelled Sandbox; cannot run live intelligencenever chargedhard cap of 25 requests/hour, 100/day and 1/second
cogv_live_production; self-serve, works immediatelypay-as-you-go: Cognivo credits per successful call from your credit balance; failed calls are never chargedyour access-mode limit, 1,000 requests/hour to start

Prototype the request shapes with a sandbox key if you like, then ship with a live key. A new live key needs no approval and no trial: it starts working the moment you create it, as long as your account has credits.

Access modes, plainly​

  • Live (standard) - self-serve pay-as-you-go. A new live key works immediately, charged in Cognivo credits per successful call at the published per-endpoint prices. If your balance cannot cover a call you get 402 payment_required (nothing charged): top up on your Cognivo account billing page and retry.
  • Sandbox - cogv_test_ keys; limited demo/testing only, cannot run live intelligence. Live calls answer 403 sandbox_limited.
  • Trial - an optional, admin-granted evaluation allowance (limited and expiring). Not required for ordinary paid use.
  • Partner - an admin-managed arrangement.
  • Enterprise - the request-access path: custom pricing, custom limits and volume. Request it from the Developer portal.
  • Suspended - the key cannot execute anything; the portal shows the reason.
  • Legacy metadata-only keys - a small number of older keys predate self-serve billing and can only call the metadata endpoints; live calls answer 403 access_required. Create a new live key to move to pay-as-you-go.

GET /v1/api/me tells you which mode your key is in (access_mode), plus your account's credits_balance and top_up guidance.

Scopes (permissions)​

Keys are default-deny: a key can only call the endpoint groups you granted when creating it. There are three scopes, and each simply unlocks a set of endpoints.

intel:read - token and wallet intelligence​

The everyday scope. It lets your key ask "what is going on with this token or wallet?": price-drop drivers, risk signals, team wallet behavior, realized PnL, and exact movements.

Unlocks: POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl, POST /v1/api/wallet/exact-movements

security:read - wallet safety scans​

Lets your key check what a wallet has approved: which contracts can spend its tokens, flagging unlimited allowances. Read-only; a key with this scope can never move funds or revoke anything.

Unlocks: POST /v1/api/wallet/approvals

liquidity:read - liquidity and LP reads​

Lets your key check whether a token's liquidity is real and where the LP tokens sit: pool context, LP custody, lock and burn context.

Unlocks: POST /v1/api/intel/liquidity

GET /v1/api/health needs no key at all, and GET /v1/api/me and GET /v1/api/discover work with any valid key, whatever its scopes.

You can edit a key's scopes any time in the portal. If a call fails with 403 scope_denied, the key simply does not carry the scope that endpoint needs.

Rotation and revocation​

  • Revoke kills a key. It stops authenticating within a minute.
  • Rotate creates a replacement key with the same name, scopes and tier, shows it once, and revokes the old key in the same step. Use it on any suspected leak and on a regular schedule.

Optional restrictions​

Per key you can additionally allow-list:

  • Origins (exact origins or wildcard subdomains like https://*.yourapp.com) - requests presenting a different Origin are rejected.
  • IPs / CIDR ranges - requests from other addresses are rejected.

Empty lists mean no restriction.

Where keys come from​

Keys are created only in the self-serve Developer portal using your existing Cognivo account. There is no manual/legacy key issuance for new integrations.