Private Integrations: Everything you need to know

Private Integrations allow you to build secure, custom connections between your GHL Customer Care account and any third-party application. This feature is ideal for internal tools, automated workflows, and custom systems that need API access without building a full public app.

IMPORTANT: For a full list of available endpoints and request/response details, visit our official API documentation: https://marketplace.https://ghlcustomercare.com/docs/

---

youtube

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?
• Testing a Private Integration with API Calls
• How do I manage Private Integrations?
• Where can I find Private Integrations?
• How do I create a new Private Integration?
• What are some best practices to maintain the security of my private integration token?
• Token compromised?
• 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 GHL Customer Care account and any other third-party app.

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

• Find and install the relevant app from the App Marketplace
• 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

Private Integrations are available for both Agencies and Sub-Accounts. To know more about the sub-accounts' Private Integrations feature, click here.

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.

Why Private Integration Tokens Are Recommended for New Credentials

Private Integration Tokens (PIT) are the recommended replacement for legacy API keys because they provide more secure and flexible access management.

Legacy API keys that remain unused for more than 90 days may be marked as Expired in settings. Because new legacy v1 key creation is no longer supported, PIT should be used for any new credentials or when migrating older integrations to a more secure access model.

If you still rely on a legacy API key, GHL Customer Care recommends moving that integration to a Private Integration Token whenever possible.

Screenshot

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, to get a location's details, you can use Get Sub-account API with the Agency's Private Integration Token in the Authorisation header.

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

curl --request POST \
  --url https://services.leadconnectorhq.com/contacts/ \
  --header 'Authorization: <YOUR PRIVATE INTEGRATION TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'Version: 2021-07-28' \
  --data '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "locationId": "LOCATION_ID"
  }'

Who can create Private Integrations?

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

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

You may apply the restrictions at two levels:

1. Allow the agency admin to view and manage the agency's private integrations
2. Allow the agency admin to view and manage the sub-accounts' private integrations

Screenshot

Where can I find Private Integrations?

You can find Private Integrations under agency settings. If you don't find it under settings, please make sure that you have enabled the feature on Labs.

Screenshot

How do I create a new Private Integration?

Step 1: Click on "Create new Integration"

Screenshot

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

Screenshot

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

Screenshot

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.

Screenshot

What are some best practices to maintain the 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.

Screenshot

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

Screenshot

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

Screenshot

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:

• "Cancel rotation" if, for example, your developer needs more time to update the token on the third-party app.
• "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. 

Screenshot

Token compromised?

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

Screenshot

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

Screenshot

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

Screenshot

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.

Screenshot

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.

Screenshot

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

Screenshot

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.

Screenshot

Users can create up to 5 Private Integration Tokens (PIT) at both the Agency level and the Location level.

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 use the third-party app. To do so, navigate to Private Integrations under settings, and select "Delete" from the three-dot menu.

Screenshot