Authentication

Every request you send to the Chronox API needs an API key. The key works like a password for your software: it tells Chronox which account the request comes from, and it decides what that request is allowed to do.

This page shows you how to create a key, how to use it in your requests, and how to keep it safe.

About API keys

An API key is a long code that you create in the Chronox dashboard. When you create one, it's linked to your user account. Anything done with the key is done as you, inside your workspace.

Good to know	Details
Shown once	You can only see the full key when you create it. After that, the dashboard shows only the first few characters.
Up to 3 keys	You can have a maximum of three active keys at a time.
Expires after one year	By default, a key stops working one year after the date shown in the Created At column.
Deleting is immediate	Once you delete a key, any request using it is refused straight away.

WARNING

Your API key has the same access to your Chronox data as you do. Keep it private: don't send it by email or chat, don't save it in shared documents, and never put it in website code that visitors can see.

Create an API key

Open the account menu

In the Chronox dashboard, click your name in the bottom-left corner. In the menu that opens, under Developer, click API Keys.

The account menu with Developer → API Keys

Open API Keys from the account menu

Check your key limit

The Key Limit box shows how many of your three keys are in use. If it shows 3 / 3 Used, delete a key you no longer need before continuing (see Delete a key).

The API Keys page showing the key limit and the list of keys

The API Keys page

Create the key

Click Create API Key and give the key a name that tells you where it's used, such as Website orders or CRM integration. The name is only for your reference.

Copy the key and store it safely

Your new key appears on screen only this once. Copy it straight away and save it somewhere secure, such as a password manager or your server's secret settings. If you lose it, you can't get it back; you'll need to create a new key.

Use your API key

Add your key to every request in a header named Authorization, with the word Bearer and a space in front of it:

Replace YOUR_API_KEY with the key you copied. Everything else stays exactly as shown.

The examples below all send the same request, Get User Details, which is the easiest way to check that your key works. Pick the tab for the tool or language you use.

cURL

JavaScript

Python

Paste this into a terminal:

If your key is working, the response contains "status": true along with your account details. If something is wrong, see When authentication fails below.

TIP

Rather than typing the key directly into your code, store it in an environment variable or your platform's secrets settings and read it from there. This keeps the key out of your code files and makes it easy to replace later.

Replace a key

There's no "renew" button. To replace a key, for example because it's about to expire or you think it's been exposed, swap it for a new one:

Make room if needed

If you already have three keys, delete one you no longer use.

Create a new key

Follow Create an API key above and copy the new key.

Update your software

Replace the old key with the new one everywhere it's used, and check that your requests still work.

Delete the old key

Once nothing is using the old key, delete it.

DANGER

If you think a key has been seen by someone else, delete it first and then create a new one. Your software will stop working until you add the new key, but no one else will be able to use the old one.

Delete a key

On the API Keys page, click the bin icon at the end of the row for the key you want to remove. The key stops working immediately, and it no longer counts towards your limit of three.

NOTE

Deleting a key can't be undone. Any software still using it will start getting errors straight away.

When authentication fails

If there's a problem with your key, the request is refused and the response explains why. A typical error response looks like this:

{
  "status": false,
  "error": {
    "code": 9243,
    "message": "Invalid or expired API key"
  }
}

The most common problems:

HTTP status	Message	What it means	What to do
`401`	ERROR! Invalid authentication found.	The request didn't include an API key, or what was sent isn't a Chronox API key.	Add the `Authorization` header exactly as shown above, with your full key.
`401`	Invalid or expired API key	The key is wrong, has been deleted, or has expired.	Check you copied the whole key. If it's expired or deleted, create a new one.
`403`	ERROR! Access not granted.	Your request reached a real Chronox endpoint, but it isn't available through the API.	Use only the endpoints listed in the sidebar.
`403`	Your account is inactive. Please contact support.	Your Chronox workspace isn't active.	Contact Chronox support.

WARNING

If the web address is mistyped, the API responds with "status": false and the message Error Invalid API Request., but the HTTP status is 200, not an error code. Always check the status field in the response, not just the HTTP status.

INFO

A 401 usually means "we don't know who you are": check the key. A 403 means "we know who you are, but you can't do this": check the endpoint or your account.

For all other errors, see Errors.

What this page doesn't cover

Logging in to the dashboard. API keys are only for software talking to the API. You still log in to the Chronox dashboard in the usual way.

Request limits. Each key can only make a certain number of requests in a short period. See Rate limiting.

About API keys#

Create an API key#

Use your API key#

Replace a key#

Delete a key#

When authentication fails#

What this page doesn't cover#

About API keys

Create an API key

Use your API key

Replace a key

Delete a key

When authentication fails

What this page doesn't cover