Skip to main content

Private Integrations: Everything You Need to Know

Table of Contents​

What are Private Integrations?​

Private Integrations allow you to create custom connections between your Stack account and other third-party applications. If you wish to integrate your Stack account with an external app, you have two options:

  1. Install an app from the App Marketplace.
  2. Build your own private integration using APIs.

Private Integrations help you securely achieve the second option.

Key Advantages​

  • Simplicity: Easily generate and manage tokens from your account settings.
  • Security: Restrict the scopes/permissions accessible by developers on your account.

Private Integrations vs. API Keys​

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

  • Security: Private Integrations let you restrict scopes/permissions, unlike API Keys, which offer unrestricted access.
  • Technology: Access API v2.0 with Private Integrations, featuring more powerful APIs and webhook support.
  • Features: API v2.0 includes more features than the outdated API v1.0 used by API Keys.

Private Integrations vs. OAuth2 Access Tokens​

Private Integrations are essentially static OAuth2 Access Tokens.

  • Generation: Easily generate tokens from the UI.
  • Static Nature: Tokens are fixed and do not refresh automatically unless rotated.
  • Comparison: Unlike Access Tokens that expire daily, Private Integration Tokens remain valid until manually rotated.

Using Private Integrations​

To use a Private Integration token, include it in the Authorization header, similar to other Access Tokens. For example, to retrieve location details, use the Get Sub-account API with the token:

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'

Managing Private Integrations​

You can manage your Private Integrations through the settings in your Stack account.

Creating a New Private Integration​

  1. Create: Click on "Create new Integration."
  2. Name & Describe: Provide a name and description for easy identification.
  3. Select Scopes: Choose the necessary scopes/permissions for your integration.
  4. Copy Token: Share the generated token with your developer. Ensure it's shared only with trusted parties.

Note: Remember to copy the token immediately as it cannot be retrieved later.

Best Practices for Security​

  • Rotate Tokens: Rotate your tokens every 90 days for enhanced security.
  • Steps to Rotate:
    1. Go to Private Integrations under settings.
    2. Click "Rotate and expire this token later."
    3. Confirm rotation and copy the new token.
    4. Update your third-party app with the new token.

During the 7-day window, both old and new tokens will work. You can cancel the rotation or expire the old token immediately, if needed.

Note: Always copy the new token as it cannot be retrieved later.

Compromised Token?​

If your token is compromised:

  1. Navigate to Private Integrations under settings.
  2. Click "Rotate and expire this token now."
  3. Confirm and copy the new token.
  4. Update your third-party app with the new token.

Note: Remember to copy the token immediately as it cannot be retrieved later.

Editing Permissions​

You can edit the name, description, and scopes/permissions of a Private Integration without updating the token.

  • Steps to Edit:
    1. Go to Private Integrations under settings.
    2. Select "Edit" from the menu.
    3. Update the necessary details and save.

Note: Editing details does not generate a new token. The existing token remains valid.

Deleting a Private Integration​

If you no longer need a Private Integration, you can delete it:

  • Navigate to Private Integrations under settings.
  • Select "Delete" from the menu.