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
Open the integration
Choose the right connection scope
Review Trigger Access
Review Tool Access
Repair or reconnect anything marked degraded
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
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.
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 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:
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
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.
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
Last updated
Was this helpful?