API keys and the IP whitelist

Create your keys #

1. Open the API tab

   Go to Settings → API. The tab is available on every paid plan, from Tier 1 up, and only to the account owner: a sub user cannot see or manage the keys. The Your plan panel at the top shows your tier, your rate limit and which areas of the API your plan includes.

2. Name it and create it

   Type a name that says where the key will be used, such as Sell bot or VPS, and click Create key. A window opens with the new key hidden as dots and a Copy button.

3. Copy it now

   Click Copy, paste the key into your password manager or your server’s secret storage, then click Done. The key is shown only this once. When the window closes it is gone from the page for good.

What a key looks like #

A key is always 64 characters: the prefix cc-api- followed by 57 random capital letters and digits.

cc-api-7Q2MZK4P9XW3B8RDT6VHN5LCJ1YFG0AESU2K9MD4PX7RB3WT6ZQ8HN5VC

That is an example, not a real key. Afterwards the API tab lists each key by its name with only the last four characters, such as cc-api-********N5VC, along with when it was created and when it was last used.

Send the key #

Put the key in the Authorization header of every request, after the word Bearer and a space. The key is case sensitive.

curl https://dashboard.consoleclient.com/api/v1/accounts \
  -H "Authorization: Bearer cc-api-YOUR_KEY_HERE"

Do not send the key in the URL or in the request body. URLs end up in logs and browser history.

Up to five keys, and revoking #

You can have up to five keys at the same time. Give each script, bot or server its own key: you can tell them apart by their last used time, and revoking one does not touch the others.

If your plan lapses, your keys stay stored but every request answers tier1_required until you renew; you can still revoke keys in the meantime. If your plan moves to a lower tier, calls to areas the new tier does not include answer tier2_required or tier3_required, and the lower limits apply from the next request.

The IP whitelist #

The IP whitelist is the single best protection for your keys, and it is recommended for everyone whose requests come from a fixed address such as a VPS or a dedicated server. One list covers all your keys. When it is on, a request is accepted only if it comes from one of the IPs on your list. A request from anywhere else is refused with ip_not_allowed, even with a valid key.

1. Find the right IP

   You need the public IP of the machine that sends the requests, not your home PC unless that is where the script runs, and not a local address such as 192.168.x.x. On a Linux server, curl ifconfig.me prints it.

2. Add it

   Type the address into the box and click Add IP. IPv4 and IPv6 are both accepted. Nothing is added automatically: only addresses you type are trusted.

3. Switch the whitelist on

   Turn on Only accept requests from the IPs below. The change applies to the very next request.

Wrong keys and lockouts #

A failed attempt is a request with a wrong or malformed key, or a request with a valid key from an IP that is not on your whitelist. After 20 failed attempts from the same IP inside 10 minutes, further failed attempts from that IP are refused with too_many_failed_attempts until the 10 minutes are up, and the response carries a Retry-After header. A request with the right key from an allowed IP is never locked out, so if a script of yours keeps sending an old key, fixing the key is enough.

If a key leaks #

1. Revoke it immediately

   Open Settings → API and click Revoke next to the leaked key. It dies at once. Then create a new key for the script that used it.

2. Check your accounts

   Look at the Overview and at Chat → Console for anything you did not do, and check Settings → Connection still points at your server.

3. Turn on the whitelist

   If it was off, add your server’s IP and switch it on so the next leak cannot be used.

4. Remove the key from wherever it leaked

   Delete the message, rotate the repository secret, or rewrite the git history. Treat the old key as public forever.