Integration & Widget · 2 min read
Private Integrations
Private integrations let you connect your account to other apps through the API. You create a token with only the permissions it needs and give it to your developer or tool.
There are two ways to connect another app:
- Install it from the App Marketplace, if it's there.
- Build your own connection with the API, using a private integration.
Why use private integrations
- Simple: create and manage tokens from your settings.
- Secure: choose exactly which permissions (scopes) each token has.
- Modern: tokens work with the current API, including webhooks.
Private integration tokens are fixed. They don't expire or refresh unless you rotate them.
Who can create them
Account admins can create and manage private integrations by default. You can limit this for individual users under user permissions.
Create a private integration
- Go to Settings > Private Integrations.
- Click Create new integration.
- Give it a name and description so you know what it's for.
- Choose the permissions it needs. Pick only what it will use.
- Click Create and copy the token.
The token is only shown once. Store it somewhere safe, like a password manager, and never post it publicly.
Use the token
Send the token in the
Authorization header of each API request, like any access token. Your developer can find the endpoints in the API documentation.Keep tokens secure
- Give each app its own token.
- Choose the fewest permissions possible.
- Rotate tokens regularly and when someone with access leaves.
If a token is exposed
Open the integration and rotate the token right away. You can expire the old token immediately or after a short overlap. Then update the app with the new token.
Change permissions
You can edit a private integration's permissions without changing the token.
Delete
Open the integration and choose Delete. Apps using the token stop working right away.