Skip to main content
An API integration is a named identity for a machine client: a backend service, a script, or a flow that keeps your tasks in step with another tool. It has its own credentials, it can only reach the Spaces you give it, and every change it makes is attributed to the integration by name, not to a person. Integrations are for root and admin users. They live under Account, then Connections, in the API integrations section.
An integration is not an API key. An API key acts as the user who made it. An integration is its own principal, takes no seat, never appears in the members list, and cannot be used to sign in. Its tokens last one hour and only work on task routes.

​
What an integration can do

Scopes are granted per Space. A Space with nothing ticked is out of reach: the integration cannot list it, read it or write to it. An integration can hold scopes on up to 500 Spaces.
Moving a task to another Space needs tasks:write on the destination as well as the source.
space:configure is deliberately narrow. It covers the Space’s name, description, default status, statuses, priorities and tags. Anything else about a Space (its owner, record sets, modules, views, logo and staging flag) is refused. When an integration writes, an unknown status, priority or tag is rejected rather than created. Create the status in the Space first, then send its id.

​
Create an integration

1

Open API integrations

Go to Account, then Connections, and find API integrations. Click Add.
2

Name it

Use a name that says what the system is, such as “Ticket sync”. The name appears on every task and comment the integration writes.
3

Choose Space access

Each Space is listed with a checkbox for each scope. Tick only what the client needs. Click Create.
4

Copy the client secret

A dialog shows the integration’s client ID and its first client secret. The secret is shown once. Copy it into your secret store before you click I have saved it.
The client secret cannot be shown again. If you lose it, rotate to issue a new one.
Your client then exchanges the pair for a one-hour token. See Task sync authentication.

​
Rotate a secret

Open the integration and use Rotate in the Secrets card. A new secret is issued and shown once. The old secret keeps working for a grace period, so you can switch your client over without downtime. Each secret shows when it was last used, which helps you confirm the old one is idle before it retires. A token minted from a retiring secret keeps working until it expires, at most an hour later. To stop a secret at once, use Revoke now on its row. Revoking ends every session the integration has open, and the next call from your client fails.

​
Disable, edit and delete

​
Webhook subscriptions

Each integration can send task events to your own endpoints. Open the integration and use Subscriptions to add an endpoint, choose the Spaces and event types, and see the signing secret. The integration needs tasks:read on a Space before you can subscribe to it.

Task webhooks

Verify signatures, handle retries and replay missed events.

​
Where to go next

Task sync

Keep tasks in step with another system using external ids, versions and the change feed.

Task sync authentication

Mint and cache an integration token.

Staging Spaces

Test a sync against a copy of your workflow.

Connect a tracker

Let the platform create and manage an integration for a supported tracker.

API keys

Programmatic access that acts as a person.