# Integrations ## What this is This section explains how Hookshot™ connections work and how to reason about integration setup. ## When to use it Use this section when you are connecting an app for the first time or repairing one that is no longer ready. ## What you need first * Permission to manage integrations in your workspace * Access to the external app you want to connect ## Steps ### 1. Understand the two kinds of access * **Trigger Access**: what can start a Protege * **Tool Access**: what a Protege can do after it starts Some integrations support both. Others may be used primarily as a source, destination, or chat surface. ### 2. Review the integration lifecycle 1. Open the integration 2. Choose the right connection scope 3. Review Trigger Access 4. Review Tool Access 5. Repair or reconnect anything marked degraded 6. Verify the setup with a real event or schedule ### 3. Choose the right connection scope Use the smallest connection scope that supports the workflow. * **Team connections** are shared by the team and fit most production Proteges. * **Personal connections** are tied to one user and should be used only when the workflow needs that user's account context. * **Chat connections** are managed at the team level for supported chat surfaces. #### Team connections A team connection uses a shared credential that belongs to the entire team. It is the right choice for: * Production Proteges that run unattended * Workflows where the action should come from the team identity, not an individual * Any scheduled Protege that runs without a specific user present Team connections: * Survive when team members leave the workspace * Can be managed by workspace admins and users with config write access * Are available to Proteges running in any mode (attended or unattended) #### Personal connections A personal connection uses a credential tied to one specific workspace user. It is the right choice for: * Workflows that need to act as a specific person (for example, creating a task assigned to that person) * Proteges that read from or write to resources only that user has access to Personal connections: * Require the owning user to remain an active workspace member * Become orphaned if the user leaves the workspace — the credential remains but cannot be resolved for any active user * Are managed by the individual user who connected them {% hint style="warning" %} If the user who owns a personal connection leaves the workspace, any Protege relying on that connection will fail for unattended runs. Use team connections for production workflows that must survive team changes. {% endhint %} #### Selected and default connections When a toolkit has both team and personal connections, Hookshot uses the **selected connection** — the one marked as the active credential for the team. For personal connections used in unattended runs, Hookshot uses the **default personal connection** — the one marked as the default for the team. This ensures scheduled Proteges have a predictable credential even when no user is present. You can see which connection is selected and which is default in the integration detail view. #### Chat connections Chat connections are always team-scoped. When you enable chat on an integration, the chat credential is managed at the team level. This is required because chat responses can be triggered at any time, including when no specific user is online. See [Chat](/create-a-protege/chat.md) for more on chat configuration. #### Auth expiry and reconnection When a connection expires or is revoked by the provider: * **Personal scope**: An email is sent to the user who owns the connection with a reconnect link * **Team scope**: An email is sent to team leads and admins with a reconnect link * The integration detail view shows the expired status and a reconnect option #### Firecrawl connection tiers Firecrawl has a unique three-tier connection model: | Tier | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Protege-provided shared** | Auto-provisioned for every team. Cannot be disconnected. Includes a disclosure that Hookshot can access scans run through it. | | **Customer-owned team** | Bring your own Firecrawl API key. When active, it replaces the shared connection as the team's default. | | **Personal** | Optional per-user Firecrawl account for member-specific scans. | ### 4. Use a consistent verification loop For every integration: * Confirm the connection is active * Confirm the right trigger source is live * Confirm the right tools are available * Confirm chat configuration is complete if the integration receives chat activity * Confirm Event Feed receives the event * Confirm Audit shows the run {% hint style="info" %} **Engineer note:** The safest way to verify an integration is end-to-end. A healthy connection screen alone does not prove that the event path and action path are both working. {% endhint %} ## How to verify You are ready to move on when you can answer: * What will start this Protege? * What will this Protege do with the integration? * Which connection scope owns the workflow? * Where will I verify that behavior? ## Common failures * Approving the connection but not checking trigger scope * Using the wrong connected account or workspace * Assuming one integration connection covers every team or project boundary * Repairing Tool Access but forgetting Trigger Access, or the reverse ## Next step * [Slack](/integrations/slack.md) * [GitHub](/integrations/github.md) * [Linear](/integrations/linear.md) * [Asana](/integrations/asana.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://gitbook.tryprotege.com/integrations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.