Skip to main content

Integrations User Guide

Use Integrations to connect workspace tools such as Slack, GitHub, Google, Microsoft, CRM systems, email providers, and custom API providers.

Browse Providers​

  • Open Integrations > Providers.
  • Search by provider name, key, or description.
  • Filter by category, auth type, and plugin status.
  • Select a provider to review supported features, scopes, documentation links, and existing workspace connections.

Provider plugin installation, editing, enable/disable, and uninstall actions are admin-only and belong in the admin integrations surface.

Create A Connection​

  • Open Integrations > Connections and choose Add Connection.
  • Select an installed and enabled provider.
  • Enter a connection name and optional description.
  • Choose credential storage.
  • Complete OAuth, API key, basic auth, or bearer-token authentication depending on the provider.

OAuth connections open the provider authorization page in a popup. The callback page sends completion back to the workspace using BroadcastChannel, postMessage, and localStorage fallback events.

Credential Storage​

  • Vault managed: integrations creates and manages a workspace vault secret for this connection.
  • Vault referenced: integrations reuses an existing active vault secret.
  • Local encrypted: legacy fallback for environments that have not enforced vault-first storage.

Production workspaces should prefer vault-managed or vault-referenced storage.

Manage Connections​

  • Use Test Connection to verify credentials exist and are not expired.
  • Use Refresh Token for OAuth connections when a refresh token is available.
  • Use Revoke to disconnect the external service and clear credentials.
  • Use Delete to soft-delete the connection. If a vault secret is mapped and no other connection uses it, you may also remove the secret.

Activity Logs​

  • Open Integrations > Activity Logs.
  • Search by message or request URL.
  • Filter by level and action.
  • Export the visible log page as CSV for local audit handoff.

Only users with integrations log read permission can view logs.

Troubleshooting​

  • If OAuth popup is blocked, allow popups for the product domain and retry.
  • If OAuth times out, verify the provider allowed redirect URI points to /integrations/oauth/callback.
  • If a connection cannot be created, verify the provider is installed and enabled.
  • If vault storage fails, verify the selected vault is active and the workspace has security-service access.
  • If decrypted token retrieval fails in workflows, verify the caller is a service actor and uses the same x-workspace-id as the connection.