Console Client
Documentation
OverviewFeaturesReviewsFAQPlansDocsStatus
Dashboard
API

API keys and the IP whitelist

Create, copy, replace, and delete your API key, and lock it to up to five IP addresses.

6 min read

Create your key

  1. Open the API tab

    Go to Settings → API. The tab is available on Tier 3, and only to the account owner: a sub user cannot see or manage the key.

  2. Generate

    Click Generate API key. The new key appears hidden, as dots, with a Copy button next to it.

  3. Copy it now

    Click Copy and paste the key into your password manager or your server’s secret storage. The key is shown only this once. When you leave the tab 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. After you leave the page, the API tab shows only the last four characters, such as cc-api-********************N5VC, so you can tell which key is active, 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.

One key, regenerate, and delete

You have one key at a time. The buttons next to the hidden key manage it.

ButtonWhat it does
RegenerateCreates a new key and kills the old one in the same moment. Anything still using the old key gets invalid_api_key until you update it. Your IP whitelist is kept.
Delete keyRemoves the key. Every request is refused until you generate a new one. Your IP whitelist is kept.

If your plan drops below Tier 3, the key stays stored but requests answer tier3_required. It works again as soon as the plan is Tier 3 again.

The IP whitelist

The IP whitelist is the single best protection for your key, and it is recommended for everyone whose requests come from a fixed address such as a VPS or a dedicated server. 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 the correct 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.

RuleDetail
Up to 5 IPsThe counter next to the heading shows how many you have used. Remove one to make room.
IPs are hiddenAs soon as you add an IP it is shown masked, for example 94.***.***.13, with only the first two and last two digits visible. Console Client stores a keyed fingerprint of the address and the masked label, never the address itself, so the full IP cannot be read back by anyone.
No editingAn IP cannot be edited once added. To change one, click Remove and add the new address.
Single addressesEach entry is one exact address. Ranges and CIDR blocks are not supported. If your server uses IPv6, note that many hosts rotate the address inside their block, so prefer the server’s IPv4 address when it has one.
On but emptyIf the whitelist is on with no IPs on the list, every request is refused. The tab warns you when this is the case.
Turning it offSwitch it off whenever you like, for example if your requests come from a home connection whose IP changes. Your list is kept for when you switch it back on.

Wrong keys and lockouts

After 20 requests with a wrong or malformed key from the same IP inside 10 minutes, that IP is refused with too_many_failed_attempts until the 10 minutes are up, and the response carries a Retry-After header. If a script of yours keeps sending an old key, fix the key and wait for the lockout to pass.

If your key leaks

  1. Regenerate immediately

    Open Settings → API and click Regenerate. The leaked key dies at once.

  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.

Good practiceWhy
Keep the key in an environment variable or a secrets manager.Keys written into code end up in git, screenshots, and pastes.
Never post the key in Discord, a ticket, or a stream.Console Client staff will never ask for it.
Use the IP whitelist.A key that only works from your server is worth nothing to a thief.
Regenerate when someone who had access leaves.There is only one key, so rotating it is quick.
Need a hand?

Check the troubleshooting guide or return to all guides.