Create and revoke an API key
Create a key with a name, scopes and an optional expiry date. The key shows only once and starts with crtk_live_. Revoking it stops it on the very next request.
Before you start · for ownersThe “Create API keys” permission, and revoking needs “Manage API keys”
Before you start · for owners
The “Create API keys” permission, and revoking needs “Manage API keys”
- You need: The “Create API keys” permission, and revoking needs “Manage API keys”
Steps
1
Open Settings → API keys and press New key.
2
In Name, type what the key is for, such as “Academy website”.
3
Under Scopes, set All units to None, Read, Write or Full, or press Add specific object to give one unit its own level: Read, Write or Full. You can also type a scope such as
read.contacts and press Enter.The details are in Key scopes, and how they combine with permissions.
4
Under Expiry (optional), pick a date, or press 90 days or 1 year. It’s recommended, but you can choose No expiry.
5
Press Create key, then Copy to copy the key straight away.
It won’t show again. The list shows only its first characters.
6
To stop it, press Revoke next to the key in the list, then Yes, revoke. Its record stays for auditing.
Where to use it
Send the key in every request in the X-Api-Key: crtk_live_... header or the Authorization: Bearer crtk_live_... header. See Authenticate requests and check a key with /me.
Changing scopes
You can’t change the scopes of an existing key. To change them, create a new key, update your integration, then revoke the old one.
Auditing
Creating and revoking a key are recorded in the audit log, without the key’s value.
If something goes wrong
What you see
Why
What to do
“You can’t grant scopes you don’t have”
Your role doesn’t have the action on that unit, such as assign set to “Denied”.
Choose a lower level, or ask the owner to create the key.
You lost the key
It isn’t shown a second time.
Create a new key and revoke the old one.
An old key refuses to change the assignee
It was created before the Write level included assigning.
Create a new key with the Write level.
Good to know
The name is up to 120 characters, with at least one scope.
You can’t create a key while signed in on behalf of another user, because the key lives on after the session.
You can’t grant a scope you don’t have.
The Viewer role can’t see keys.
A key can’t be created or revoked using a key.
Did this guide solve it?
If not, we’ll ask what was missing.