> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Private integrations

> Create secure OAuth access tokens with scoped permissions to connect external applications to the HoopAI Platform API v2.

Private Integrations is designed to enhance the security and functionality of your account integrations. By moving beyond the limitations of API keys, Private Integrations offers a more robust, secure, and manageable solution for connecting third-party applications to your account.

Navigate to **Settings > Private Integrations** to get started.

## Key features

* **Enhanced security** — restrict the scopes and permissions that a developer can access on your account, providing a higher level of security compared to API keys
* **Feature-rich API access** — Private Integrations grant access to API v2.0, which includes more API features and Webhooks, expanding the possibilities for custom integrations
* **Token management** — includes token management best practices such as Rotate and Expire Now/Later, making it easier to manage your integrations securely and efficiently

<Note>
  Private Integrations are the recommended migration path for customers using custom integrations built on API v1. API v2 offers better security, more features, and improved management controls.
</Note>

***

## Creating a private integration

<Steps>
  <Step title="Navigate to Private Integrations">
    Go to **Settings > Private Integrations**, then click **Create New Integration**.

    <Frame caption="Private Integrations overview">
      <img src="https://mintcdn.com/hoopai-84ec0cdc/uCdCimKFr6Ug8R7X/images/settings-private-integration.png?fit=max&auto=format&n=uCdCimKFr6Ug8R7X&q=85&s=8000ca874e486e1689c02ffcfdee3fb1" alt="Private Integration" width="1514" height="825" data-path="images/settings-private-integration.png" />
    </Frame>
  </Step>

  <Step title="Enter basic information">
    Configure the integration details:

    * **Integration name** — give your integration a meaningful name to identify it easily
    * **Description** — provide a brief description of what the integration does

    <Frame caption="Basic info configuration">
      <img src="https://mintcdn.com/hoopai-84ec0cdc/uCdCimKFr6Ug8R7X/images/settings-private-integration-basic-info.png?fit=max&auto=format&n=uCdCimKFr6Ug8R7X&q=85&s=9238d169ea7a8e49388e1aa34a21f029" alt="Basic Info" width="1417" height="748" data-path="images/settings-private-integration-basic-info.png" />
    </Frame>
  </Step>

  <Step title="Define scopes">
    Define the scopes and permissions that the third-party application will have access to. Restricting scopes to only what is necessary is crucial for maintaining security.

    <Frame caption="Selecting scopes and permissions">
      <img src="https://mintcdn.com/hoopai-84ec0cdc/uCdCimKFr6Ug8R7X/images/settings-private-integration-scopes.gif?s=0717b2ae110bc1bd5835550c786607da" alt="Scopes" width="1564" height="844" data-path="images/settings-private-integration-scopes.gif" />
    </Frame>
  </Step>

  <Step title="Generate an access token">
    Click **Generate Access Token**. This token will be used by the third-party application to authenticate with your account.

    <Frame caption="Copy the access token">
      <img src="https://mintcdn.com/hoopai-84ec0cdc/uCdCimKFr6Ug8R7X/images/settings-private-integration-copy.png?fit=max&auto=format&n=uCdCimKFr6Ug8R7X&q=85&s=89f4ca7c5b01545e880826845889d8f7" alt="Copy token" width="1381" height="718" data-path="images/settings-private-integration-copy.png" />
    </Frame>

    <Warning>
      Copy and store the access token securely — it will not be displayed again after you leave this screen.
    </Warning>
  </Step>

  <Step title="Test the integration">
    Use the access token to connect your third-party application with the platform. Test the integration to ensure it works as expected and has the correct permissions.
  </Step>
</Steps>

***

## Managing integration tokens

After creating an integration, you can manage its tokens from the **Private Integrations** tab:

<Frame caption="Token management options">
  <img src="https://mintcdn.com/hoopai-84ec0cdc/uCdCimKFr6Ug8R7X/images/settings-private-integration-rotate.png?fit=max&auto=format&n=uCdCimKFr6Ug8R7X&q=85&s=2cfbdb0b3598facda1bdae28b084cdb2" alt="Rotate token" width="1662" height="687" data-path="images/settings-private-integration-rotate.png" />
</Frame>

| Action           | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| **Rotate Now**   | Generates a new token immediately and invalidates the old one          |
| **Expire Now**   | Immediately invalidates the current token without generating a new one |
| **Expire Later** | Schedule a future expiration date for a planned rotation               |

<Tip>
  Regularly rotate your integration tokens using the Rotate Now feature to enhance security, especially for integrations with broad API access scopes.
</Tip>

***

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do Private Integrations improve security compared to API keys?">
    Private Integrations allow you to restrict the scopes and permissions that developers can access, reducing the risk of unauthorized access. API keys provide broad access, while Private Integration tokens can be scoped to only the specific data and actions the integration needs.
  </Accordion>

  <Accordion title="What are the benefits of API v2.0 access?">
    API v2.0 includes more features and Webhooks, providing greater functionality and flexibility for custom integrations compared to API v1. Private Integrations exclusively use API v2.0.
  </Accordion>

  <Accordion title="How can I manage my integration tokens effectively?">
    Follow these best practices:

    * Rotate tokens regularly using the Rotate Now feature
    * Expire tokens immediately if you suspect they have been compromised
    * Monitor token usage and set expiry dates for time-limited integrations
    * Keep token names descriptive so you can identify each integration's purpose
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

| Issue                           | Solution                                                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Unauthorized API errors**     | Verify the correct token is being passed in the Authorization header and that the required scopes are enabled |
| **Integration stopped working** | Check if the token was rotated or expired — generate a new token if needed                                    |
| **Missing API features**        | Ensure your integration is using API v2.0 endpoints, not v1                                                   |
| **Scope errors**                | Review the scopes assigned to the integration and add any missing permissions                                 |

***

## Related articles

* [Integrations](/settings/integrations)
* [External tracking](/settings/external-tracking)
* [Audit logs](/settings/audit-logs)