Authentication, scopes, and permissions

FastHook uses connected provider accounts to create Trigger subscriptions, load remote resource options, and execute Actions. An account belongs to the selected FastHook team. Sources and Workflow Steps in another team cannot use it.

Choose the authentication model

| Model | Typical use | How access changes | | --- | --- | --- | | OAuth 2.0 | Google, Slack, Stripe, Shopify, HubSpot, Linear, Notion, Dropbox, Microsoft, Airtable, GitLab, Jira, and Trello | Reconnect the account and approve the current scopes. | | App installation | GitHub | Change the installation’s repository or organization access, then reconnect when required. | | API credentials | Twilio, Telegram, and PayPal | Rotate or replace the credential in both the provider and FastHook. | | Managed bot, customer bot, or customer webhook | Discord Actions | Select a mode supported by the Action; fields and permissions change with that mode. |

The provider manifest determines which model and modes the current Trigger or Action supports. Do not copy a credential into a text mapping when the editor expects a connected account.

How FastHook determines OAuth scopes

The authorization request combines the provider’s base scopes with requirements from the selected Trigger definition, its event configuration, and the selected Action. Some custom event selectors calculate scopes from the event types you choose.

Connecting or reconnecting OAuth requires a signed-in dashboard session. The authorization state expires after 10 minutes and can be used only once. If the provider callback is delayed, expired, opened under another user, or submitted twice, start the connection again from FastHook.

Each provider reference lists its current base Trigger scopes and operation-specific Action requirements generated from the backend manifests.

Scope is not the same as resource access

An OAuth scope permits a category of API operation. It does not automatically grant the connected identity access to every resource in that category.

For example:

• A Slack app can have message scopes but still be absent from a private channel.
• A GitHub App can support issue Actions but only for repositories included in its installation.
• A Google account can have Drive or Sheets scopes but lack access to a shared drive or spreadsheet.
• A Notion integration only sees pages and data sources shared with it.
• A Jira or Linear user can consent successfully while lacking access to one project or team.

When a remote picker is empty, verify provider-side membership and object access before reconnecting repeatedly.

Account lifecycle

Connected-account responses expose a lifecycle state derived from credentials and provider status:

| State | Meaning | Operator action | | --- | --- | --- | | active | Enabled with no known expiry or stored error. | Use it and test the selected operation. | | expired | The recorded provider token lifetime has passed. | Reconnect the account. | | error | FastHook recorded a provider or subscription error. | Inspect the error, fix provider access, then reconnect or reconcile. | | revoked | The account was disabled or explicitly revoked. | Connect again only after confirming the intended security boundary. |

An Action rejects a missing provider account with 404. A disabled account, missing credentials, wrong Discord connection kind, or missing required scopes normally produces 409 with a reconnect or selection instruction.

Connect with least privilege

1. Select the exact Trigger event or Action before connecting when possible.
2. Review the provider consent screen and the operation requirements in the provider reference.
3. Grant only the workspaces, repositories, stores, drives, bases, channels, or projects the Workflow needs.
4. Use separate accounts for production and test environments, different customers, or strict permission boundaries.
5. Give the account a descriptive name that identifies the provider workspace and environment.
6. Produce one controlled event or Action and verify both FastHook Audit and the provider result.

Do not share one broadly privileged account merely to make resource pickers easier to populate. Account reuse also creates a shared dependency: one revocation can affect every linked Source and Action.

Reconnect safely

Reconnect when required scopes changed, a refresh credential expired, consent was withdrawn, an installation changed, or FastHook reports that credentials are unavailable.

1. Pause affected Workflows when repeated provider calls could create noise or failed side effects.
2. Open Settings → Connected accounts and identify the exact account used by Audit.
3. Reconnect from the affected Trigger or Action so its current scope requirements are included.
4. Confirm the lifecycle returns to active.
5. Reopen affected Sources and Actions and reload their remote resource pickers.
6. Run one controlled test and inspect the Step response status, attempt, and output.
7. Reactivate paused Workflows after the provider result is correct.

Reconnecting can repair authorization, but it does not restore a deleted resource or provider role.

Rotate API credentials

1. Create or rotate the secret at the provider.
2. Replace the connected FastHook credential immediately.
3. Test one read or low-impact Action where the provider supports it.
4. Revoke the previous credential after the new connection succeeds.
5. Review Workflow Audit for unauthorized attempts or unexpected use.

Secret fields are stored as credentials and are not returned as ordinary API data. Never place bot tokens, client secrets, auth tokens, webhook credentials, or refresh tokens in Workflow names, descriptions, mappings, fixtures, logs, or screenshots.

Diagnose an authorization failure

| Symptom | Check first | Resolution | | --- | --- | --- | | Account is not listed | Active FastHook team, provider key, and Action auth mode | Switch team or connect the correct provider account. | | Picker is empty | Provider-side access to the selected resource | Add the identity or installation to the resource, then reload. | | Missing-scope message | Required scopes for the exact operation | Reconnect from that Trigger or Action. | | HTTP 401 | Expired, revoked, or invalid provider credential | Reconnect or replace credentials; do not retry indefinitely. | | HTTP 403 | Provider role, object permission, app installation, or tenant policy | Grant provider-side access or select another resource/account. | | HTTP 409 from FastHook setup | Disabled account, wrong account kind, missing credentials, or missing scopes | Follow the response instruction and save the Action again. | | Trigger stopped | Provider subscription/channel status and account lifecycle | Reconnect, then verify or recreate the Source subscription. | | Action worked before | Resource deletion, membership change, scope change, or credential rotation | Compare the failing run with the last successful run in Audit. |

If authentication succeeds but the provider returns 429 or 5xx, treat it as a rate-limit or availability problem rather than a consent problem. Continue with Workflow error handling and Limits, statuses, and error codes.

Revoke an account

Before revoking, inspect how many Sources, Actions, and lookups use the account. Pause affected Workflows if losing access would cause repeated failures.

FastHook disables the account and clears its usable credential material. It also attempts provider-side revocation and stops related managed channels where supported. Some providers require additional cleanup in their own console, especially for app installations, webhooks, or manually issued credentials.

Next, manage account reuse and revocation in Connected accounts, or choose a provider from the integration catalog.