API keys

An API key lets one of your systems, such as a website, a script or an automation tool, call the REST API on behalf of your company. This page explains who can make keys, what a key can do, and how to replace or cancel one safely.

Before you start

• Plan: keys are available when your plan includes API access. Without it, the API keys screen is not shown and every existing key is refused with 403.
• Role: only owners and administrators can open API keys, create keys and revoke them. Members and viewers cannot.
• Where: open Contacts in the sidebar, then Tools, then API keys.

How a key works

A key always acts as the person who created it, with that person's current role. Nothing about the key itself changes when the person changes, but what it can do follows them on every request:

Each key also has one of two access levels:

Give each system the least it needs. A reporting script needs Read only. A website that creates contacts needs Read and write.

Create a key

1. Open Contacts, then Tools, then API keys.
2. Under Create key, type a Key name that says where the key will be used, for example "Website contact form". Names can be up to 80 characters.
3. Choose the Access level: Read only or Read and write.
4. Select Create key.
5. Copy the key from the box that says Copy this key now. It will not be shown again. and store it in your system's secret settings.

The key is shown only once. It is stored as a one-way hash, so nobody, including support, can show it to you again. If you lose it, create a new key and revoke the old one.

Keys start with a short word and an underscore, followed by 48 random characters. This guide writes them as YOUR_API_KEY. Treat the whole string as a password.

See your keys

The API keys screen lists every active key with its name, the last eight characters of the key, its access level, and when it was last used (Last used with a date, or Never used). The last-used date is refreshed at most once a minute, so it is a guide rather than an exact log.

Rotate a key

There is no button that changes an existing key, so you rotate by overlapping two keys:

1. Create a new key with the same access level and a name that marks it as new.
2. Put the new key into your system and deploy the change.
3. Wait until the new key shows a Last used date, which confirms your system is using it.
4. Select Revoke next to the old key.

Rotate when someone who had the key leaves, when a key may have been exposed, and on a regular schedule that suits your security policy.

Revoke a key

Select Revoke next to the key. Revocation is immediate: the next request with that key returns 401 Invalid API key. A revoked key cannot be restored. It disappears from the list and no longer counts towards the limit.

Good to know

• A company can have up to 10 active keys. Creating an eleventh shows This company has reached 10 active keys. Revoke a key you no longer need first.
• A key belongs to one company. It never sees another company's data, even if its creator belongs to several.
• Keys keep working when the product name changes. A key is recognised by its hash, not by its first word.
• Never put a key in a web page, a mobile app or any code a visitor can download. The API sends no cross-origin headers, so browsers cannot call it anyway. Call it from your server.
• Use a separate key for each system, so you can revoke one without stopping the others.

Troubleshooting