Key features
- Enhanced security — restrict the scopes and permissions that a developer can access on your account, providing a higher level of security compared to API keys
- Feature-rich API access — Private Integrations grant access to API v2.0, which includes more API features and Webhooks, expanding the possibilities for custom integrations
- Token management — includes token management best practices such as Rotate and Expire Now/Later, making it easier to manage your integrations securely and efficiently
Private Integrations are the recommended migration path for customers using custom integrations built on API v1. API v2 offers better security, more features, and improved management controls.
Creating a private integration
Navigate to Private Integrations
Go to Settings > Private Integrations, then click Create New Integration.
Enter basic information
Configure the integration details:
- Integration name — give your integration a meaningful name to identify it easily
- Description — provide a brief description of what the integration does
Define scopes
Define the scopes and permissions that the third-party application will have access to. Restricting scopes to only what is necessary is crucial for maintaining security.
Generate an access token
Click Generate Access Token. This token will be used by the third-party application to authenticate with your account.
Managing integration tokens
After creating an integration, you can manage its tokens from the Private Integrations tab:
| Action | Description |
|---|---|
| Rotate Now | Generates a new token immediately and invalidates the old one |
| Expire Now | Immediately invalidates the current token without generating a new one |
| Expire Later | Schedule a future expiration date for a planned rotation |
Frequently asked questions
How do Private Integrations improve security compared to API keys?
How do Private Integrations improve security compared to API keys?
Private Integrations allow you to restrict the scopes and permissions that developers can access, reducing the risk of unauthorized access. API keys provide broad access, while Private Integration tokens can be scoped to only the specific data and actions the integration needs.
What are the benefits of API v2.0 access?
What are the benefits of API v2.0 access?
API v2.0 includes more features and Webhooks, providing greater functionality and flexibility for custom integrations compared to API v1. Private Integrations exclusively use API v2.0.
How can I manage my integration tokens effectively?
How can I manage my integration tokens effectively?
Follow these best practices:
- Rotate tokens regularly using the Rotate Now feature
- Expire tokens immediately if you suspect they have been compromised
- Monitor token usage and set expiry dates for time-limited integrations
- Keep token names descriptive so you can identify each integration’s purpose
Troubleshooting
| Issue | Solution |
|---|---|
| Unauthorized API errors | Verify the correct token is being passed in the Authorization header and that the required scopes are enabled |
| Integration stopped working | Check if the token was rotated or expired — generate a new token if needed |
| Missing API features | Ensure your integration is using API v2.0 endpoints, not v1 |
| Scope errors | Review the scopes assigned to the integration and add any missing permissions |