Token authentication

Every request to the API is authenticated with an API key: a randomly generated string of 64 characters. Send it in the Authorization header of each request:

Authorization: Token <your_64_char_api_key>

A request without a valid key returns 401 Unauthorized. See HTTP response codes.

Create an API key

1. In the User app, go to Workspace Settings → API & Integrations → Public API.
2. Click New API Key.
3. Fill in the key's settings (described below).
4. Click Save. The full key is shown once. Copy it right away and store it somewhere secure, such as a password manager. After you close the window, the key is masked and can't be shown again.

Key settings

Setting	What it does
Name	A name for the integration or project that uses the key. It helps you tell keys apart later.
Scope	What the key is allowed to do. See Scopes.
Day of expire	The day the key stops working. Recommended for temporary projects.

Two weeks before a key expires, User sends an email to the person who created the key and to the workspace owner, so an integration doesn't stop unexpectedly.

Once a key has expired, requests with it return 401 Unauthorized:

{
  "detail": "Token has expired."
}

Scopes

Scope	The key can
Read Only	Read data (GET requests). It can't create, change or delete anything.
Write Only	Create, change and delete data (POST, PUT, PATCH and DELETE). It can't read anything.
All	Read, create, change and delete data (every method).

Give each key the narrowest scope its integration needs. For example, a script that only exports contacts needs Read Only.

A request the key's scope doesn't allow returns 403 Forbidden, before the request itself is checked: any POST, PUT, PATCH or DELETE with a Read Only key, and any GET with a Write Only key. The body is:

{
  "detail": "You do not have permission to perform this action."
}

IP whitelisting

You can list the IP addresses allowed to use your API keys, such as your servers or office. Then a leaked key can't be used from anywhere else.

• Whitelisting turns on as soon as you add the first IP address.
• The list applies to every API key in the workspace, not to a single key.
• A request from an address that isn't on the list returns 403 Forbidden:

{
  "detail": "Your IP address is not allowed."
}

CHECK THE ADDRESSES

Once the list is on, requests from any address not on it are blocked. A wrong address blocks your own integrations.

Replace a key

To replace a key without stopping an integration, for example before it expires:

1. Create a new key with the same scope.
2. Switch the integration to the new key.
3. When the integration works with the new key, revoke the old one.

Keep keys secure

• Use a separate key for each integration. You can then see which integration does what, and revoke one key without affecting the others.
• Keep keys on the server. Never put a key in client-side code, such as JavaScript on your web pages, where anyone can read it. Keep it in an environment variable or a secrets manager.
• Treat keys like passwords. Don't share them in public places, such as forums, tickets or code repositories.
• Set an expiry date. Old and unused keys then don't stay active indefinitely.

For more on managing keys in the app, see How to create and manage API keys in the Help Center.