Private Integrations: Everything you need to know

Table of contents

• What are Private Integrations?
• What's the difference between Private Integrations and API Keys?
• What's the difference between Private Integrations and OAuth2 Access Tokens?
• How do I use Private Integrations?
• How do I use Private Integrations?
  • Who can create Private Integrations?
  • Where can I find Private Integrations?
  • How do I create a new Private Integration?
  • What are some best practices to maintain security of my private integration token?
  • My token has been compromised? What should I do?
  • Can I edit the Private Integration permissions without updating the token?
  • How do I delete the Private Integration once I no longer need it?

What are Private Integrations?

Private Integrations allows you to build powerful custom integrations between your account and any other third party app. 

If you are looking to integrate your account with a third party app, you have two options:

1. Find and install relevant app from the App Marketplace

2. Build your own private integration by yourself or with the help of a developer using APIs.

Private Integrations helps you achieve #2 securely.

The key advantages of using Private Integrations are:

• Simple: Generate Private Integration tokens from your account settings and manage them with ease.
• Secure: You get to restrict the scopes/permissions that a developer can access on your account

What's the difference between Private Integrations and API Keys?

Private Integrations, to put it simply, is more powerful yet secure alternative to API Keys.

What's the difference between Private Integrations and OAuth2 Access Tokens?

Private Integrations, to put it simply, is static/fixed OAuth2 Access Tokens.

How do I use Private Integrations?

Private Integration tokens are used in the Authorisation header, just like other Access Tokens.
For example, you can use GET Contact with the Private Integration Token in the Authorisation header.

curl --request GET \  --url https://services.leadconnectorhq.com/contacts/ocQHyuzHvysMo5N5VsXc \  --header 'Accept: application/json' \  --header 'Authorization: <YOUR PRIVATE INTEGRATION TOKEN>' \  --header 'Version: 2021-07-28'

How do I use Private Integrations?

Who can create Private Integrations?

By default, all account admins can create and manage Private Integrations. 

However, you can restrict this permission at a user level. To do this, Navigate to Settings > My Staff > Edit the specific account admin > Roles & Permissions, and enable/disable Private Integrations for the admin.

Where can I find Private Integrations?

To manage Private Integrations, go to Settings and scroll down to the 'Other Settings' section in the left navigation menu. 

If you don't find the setting, please make sure that you have enabled the feature on Labs.

How do I create a new Private Integration?

Step 1: Click on "Create new Integration"

Step 2: Give your Private Integration a name and description to help you and your team identify what it's for.

Step 3: Select the scopes/permissions that you want the private integration to have access to on your account. Ensure that you are selecting only the required scopes for better data security.

Step 4: Copy the token generated and share it with your third-party app developer. 

Please ensure that you are sharing the token with trusted parties only. Do not share it publicly.

Note: Don't forget to copy the token generated as you won't be able to do it again later.

What are some best practices to maintain security of my private integration token?

We recommend that you rotate your Private Integration tokens every 90 days.

Here's how you can do it.

Step 1: Navigate to Private Integrations under settings, and click on the Private Integration you have created.

Step 2: Click on "Rotate and expire this token later".

Step 3: Click "Continue" in response to the warning message if you are sure that you want to proceed with rotation. 

Step 4: Copy the new token and update it on your third-party app. You will have a 7 day window where both the old and the new tokens will continue to work. After 7 days, the old token will expire. In this 7 day window, you will have the option to:

1. "Cancel rotation" if, for example, your developer needs more time to update the token on the third-party app.

2. "Expire Now", if, for example, the third party app has been updated with the new token.

Note: Don't forget to copy the token generated as you won't be able to do it again later. 

My token has been compromised? What should I do?

Step 1: Navigate to Private Integrations under settings, and click on the Private Integration you have created.

Step 2: Click on "Rotate and expire this token now".

Step 3: Click "Continue" in response to the warning message if you are sure that you want to proceed with rotation. 

Step 4: Copy the new token and update it on your third-party app.

Note: Don't forget to copy the token generated as you won't be able to do it again later.

Can I edit the Private Integration permissions without updating the token?

Yes, you can edit the Private Integration name, description and scopes/permissions any time after you've created it.

Here's how you can do it.

Step 1: Navigate to Private Integrations under settings, and select "Edit" from the three-dot menu.

Step 2: Update the Private Integration name and description if required. Click on "Next".

Step 3: If required, update the scopes/permissions that you want the private integration to have access to on your account. Ensure that you are selecting only the required scopes for better data security. Click on "Update" to save the updates made.

Note: Updating the Private Integration details does not generate a new token. The existing token will continue to work.

How do I delete the Private Integration once I no longer need it?

You can delete the Private Integration once you no longer are using the third-party app.

To do so, navigate to Private Integrations under settings, and select "Delete" from the three-dot menu.