Understanding and Managing Private Integrations

What Are Private Integrations?

Private Integrations are a feature that enables you to establish secure, custom connections between your CRM account and external third-party applications. This is the ideal solution for creating automated workflows, connecting to internal tools, or integrating with custom systems that require API access, without the need to develop and publish a full public application.

If you wish to connect your CRM with another service, you generally have two paths: you can search for and install a pre-built application from the App Marketplace, or you can build your own custom integration. Private Integrations provide the framework for building your own integration securely.

The primary benefits of using Private Integrations include:

• Simplicity: You can easily generate and manage your integration tokens directly from your account settings.
• Security: You have granular control, allowing you to restrict the specific data and functions (scopes/permissions) that the integration can access within your account.

This feature is available for use at both the agency level and for individual sub-accounts.

Private Integrations vs. API Keys

Private Integrations are a more secure and advanced alternative to traditional API Keys.

• Security: Private Integrations allow you to define specific permissions, whereas an API key typically grants unrestricted access to all account data.
• Technology: Private Integrations utilize the modern API v2.0, which is actively maintained and includes more powerful features. API Keys are tied to the outdated API v1.0, which is no longer being updated.

For any new credentials, Private Integration Tokens are the recommended method. Legacy API keys that go unused for an extended period may be marked as expired. Since creating new v1 API keys is no longer supported, you should use Private Integrations for new projects or when updating older integrations.

Private Integrations vs. OAuth2 Access Tokens

Think of a Private Integration as a static, or fixed, OAuth2 Access Token.

• Generation: Private Integration tokens are generated directly within the CRM's user interface. OAuth2 Access Tokens are generated programmatically by exchanging an authorization code via an API.
• Longevity: Private Integration Tokens are static and do not expire automatically; you must manually rotate them if needed. Standard OAuth2 Access Tokens have a short lifespan and must be refreshed frequently, often daily.

How to Use Private Integrations

To use a Private Integration, you include its token in the Authorization header of your API requests, just like other bearer tokens. For instance, to retrieve details for a specific location, you would send a GET request to the appropriate endpoint with your token in the header.

Testing a Private Integration with API Calls

After creating your integration, you can test it by making API calls. For example, to create a new contact, you would send a POST request to the contacts endpoint.

When testing, ensure you:

• Replace LOCATION_ID with the actual ID of your sub-account.
• Replace the placeholder in the Authorization header with your actual Private Integration token.

For a complete list of available API endpoints and detailed request/response specifications, please consult the official API documentation.

Managing Private Integrations

Who Can Create Private Integrations?

By default, all users with agency administrator privileges can create and manage Private Integrations. You can control this permission for individual team members.

To adjust these permissions:

1. Go to Settings > Team.
2. Edit the profile of the specific agency admin.
3. Navigate to the Roles & Permissions section.
4. Here, you can enable or disable the ability for that user to view and manage Private Integrations for the agency itself, as well as for any sub-accounts.

Where to Find Private Integrations

You can access the Private Integrations management area within your agency settings. If you do not see this option, confirm that the feature is enabled in the Labs section of your settings.

Creating a New Private Integration

To create a new integration, navigate to the Private Integrations section in your settings and select the option to create a new one. You will be prompted to name the integration and select the specific permissions (scopes) it requires. After confirming your selections, a unique token will be generated.

Best Practices for Security

• Treat your Private Integration token with the same level of secrecy as a password.
• Only grant the minimum permissions necessary for the integration to function.
• Avoid embedding the token directly in client-side code or public repositories.

If Your Token Is Compromised

If you suspect your token has been exposed, you should immediately rotate (regenerate) it from the Private Integrations management page. This will invalidate the old token and issue a new one, which you must then update in your integration's code.

Editing Permissions

Yes, you can modify the permissions assigned to a Private Integration after it has been created. When you edit the scopes, the existing token remains valid and will immediately reflect the new permission set; you do not need to generate a new token.

Deleting a Private Integration

If you no longer need an integration, you can delete it from the management page. This action is permanent and will immediately revoke API access for that token.