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
serviceactor and uses the samex-workspace-idas the connection.