Create and manage private integrations

Private Integrations create custom connections between a JourneyCARE account and a third-party application, giving internal tools, automated workflows, and custom systems API access without a full public app. This article covers what private integrations are, creating one, using and testing its token, controlling permissions, and rotating, editing, and deleting tokens.

What Private Integrations are

Private Integrations are custom API connections between your JourneyCARE account and a third-party application, available for organizations and sub-accounts. They are intended for internal tools, automated workflows, and custom systems that need API access without a full public app.

For third-party connections you have two options: find and install an app from the App Marketplace, or build a private integration using APIs. Private Integrations are simple, because tokens are generated from account settings, and secure, because scopes and permissions can be restricted.

Private Integrations vs API keys

Choose a Private Integration for new API access: Private Integration Tokens restrict scopes and permissions and use the maintained API v2.0, while API keys have unrestricted developer access and use the end-of-life API v1.0.

Private Integration Tokens (PIT) are the recommended replacement for legacy API keys. Legacy API keys unused for more than 90 days may be marked Expired in settings, and creating new legacy v1 keys is no longer supported. Move existing legacy integrations to Private Integration Tokens when possible.

Private Integrations vs OAuth2 access tokens

Private Integration Tokens are generated from the UI and stay fixed until you rotate them, while OAuth2 access tokens are generated programmatically and expire daily.

Find Private Integrations

Private Integrations are found under organization settings. If the option is not visible under Settings, enable the feature in Labs.

Control who can manage Private Integrations

By default, all organization admins can create and manage Private Integrations. To restrict that, apply the permission at the user level.

1. Go to Settings > Team.

2. Edit the specific organization admin.

3. Open Roles & Permissions.

4. Enable or disable Private Integrations.

Two permission levels are available:

• Allow the organization admin to view and manage the organization's private integrations.

• Allow the organization admin to view and manage sub-accounts' private integrations.

Create a Private Integration

Create a Private Integration when an internal tool, automated workflow, or custom system needs API access: choose its scopes and permissions, then copy the generated token immediately.

1. Click Create new Integration.

2. Enter a name and description so the integration can be identified.

3. Select the required scopes and permissions for the organization account.

4. Copy the generated token and share it only with trusted third parties.

Use and test the token

Send the private integration token in the Authorization header of API requests, the same way other access tokens are sent.

To test a private integration with API calls, use the correct API endpoint URL for the action you want to perform. The example test is adding a new contact: replace LOCATION_ID in the endpoint URL with the actual sub-account ID, and replace the Authorization value with the generated token.

Rotate a token

Rotate tokens regularly as a security best practice; rotation is recommended every 90 days.

1. Navigate to Private Integrations under Settings.

2. Click the Private Integration.

3. Click Rotate and expire this token later.

4. Click Continue in the warning message.

5. Copy the new token and update it in the third-party application.

After rotation, both the old and new tokens continue working for 7 days. During that window, select Cancel rotation if the third-party update needs more time, or select Expire Now once the third-party application has been updated. The generated token cannot be copied again later, so copy it now.

Respond to a compromised token

If a token is compromised, rotate and expire it now so the old token stops working immediately.

1. Navigate to Private Integrations under Settings.

2. Click the Private Integration.

3. Click Rotate and expire this token now.

4. Click Continue in the warning message.

5. Copy the new token and update it in the third-party application.

The same one-time-copy rule applies: the generated token cannot be copied again later, so copy the new token now.

Edit a Private Integration

Edit the name, description, and scopes and permissions after creation; editing does not create a new token.

1. Navigate to Private Integrations under Settings.

2. Open the three-dot menu and select Edit.

3. Update the name and description, then click Next.

4. Update scopes and permissions if required.

5. Click Update.

Delete a Private Integration

Delete a Private Integration when it is no longer needed.

1. Navigate to Private Integrations under Settings.

2. Open the three-dot menu.

3. Select Delete.

Private Integrations FAQs