Create and revoke a personal API token

Steps

1. 1

   Open API Tokens

   Go to Settings → Personal → My connections → API Tokens. The tab appears only if API access is on for your user, which it is by default for everyone who signs up or accepts an invitation.

2. 2

   Create the token

   Click New token, enter a Token name that says where it is used, such as accounting-sync, and click Create.

3. 3

   Work around the known issue

   In the current build the screen does not display the new token's value, even though it was created. Until this is fixed, a developer can get a Bearer token from POST /api/token with email, password and device_name, as in the example below.

4. 4

   Use the token

   Send it in the Authorization: Bearer header on every request to endpoints such as /api/contacts or /api/deals, and name the workspace in the X-Tenant-Slug header.

5. 5

   Revoke it when finished

   Delete it with the trash icon on API Tokens, or go to My Account → Sessions & Security, where Access tokens lists each token with its last use and offers Revoke token and Revoke all.

Worked example

Replace the address and bracketed values with your own:

# 1) Get a token
curl -X POST https://<app-address>/api/token \
  -H "Content-Type: application/json" \
  -d '{"email":"integration@company.com","password":"<password>","device_name":"erp-sync"}'

# 1b) Only if two-factor is on: send the challenge_token from the previous response with the app code, within 5 minutes and from the same network
curl -X POST https://<app-address>/api/token/2fa-challenge \
  -H "Content-Type: application/json" \
  -d '{"challenge_token":"<challenge_token>","code":"<6-digit-code>"}'

# 2) List contacts with it
curl https://<app-address>/api/contacts \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Slug: <workspace-slug>" \
  -H "Accept: application/json"

The first call returns the token in the accessToken field. If two-factor authentication is on for the account, it returns requires_two_factor and a challenge_token instead, and call 1b issues the token once you supply the authenticator code.

Security advice

• A token carries its owner's full permissions. There are no scoped or read-only tokens, so create a dedicated integration user with a limited role and use that user's token.
• Tokens expire after 14 days by default. Plan for renewal in long-running integrations. If the integration user has two-factor on, each renewal needs a person to enter the authenticator code.
• Suspending a user kills their tokens immediately, so do not tie a critical integration to an employee who may leave.
• Workspace admins cannot restrict API access per user, so ask each teammate to review their active tokens under Sessions & Security and revoke any they no longer use.

There is no published OpenAPI documentation yet. For the available resources see the REST API page; to have events pushed to your system instead of polling, see setting up outgoing webhooks.