Connecting Integration Agents
Integration agents — like Google, Slack, Jira, and others — need an OAuth connection before they can work. This page explains how to connect them, what permissions they request, and how disconnection works.
How OAuth connection works
Connecting an integration agent follows a standard OAuth flow:
- Click Connect — In the Integrations page, click the Connect button for the service you want
- Redirect to provider — You're sent to the service's authorization page (e.g., Google's consent screen)
- Authorize scopes — Review and approve the permissions Thallus requests
- Token stored — The access token and refresh token are encrypted and stored securely
- Agent available — The agent's availability cache is invalidated and the agent becomes available for planning
Each connection is per-user. Your OAuth tokens are not shared with other members of your organization.
Available integrations
Here's every integration agent and its connection method:
| Agent | Auth Method | Capabilities |
|---|---|---|
| OAuth 2.0 | Gmail, Calendar, Contacts, Drive | |
| Microsoft 365 | OAuth 2.0 | Outlook, Calendar, Contacts, OneDrive, Teams |
| Slack | OAuth 2.0 | Channels, messages, search, reactions |
| Jira | OAuth 2.0 | Issues, projects, sprints, comments |
| Linear | OAuth 2.0 | Issues, projects, comments |
| GitHub | OAuth 2.0 | Repos, issues, PRs, commits |
| HubSpot | OAuth 2.0 | Contacts, companies, deals |
| Salesforce | OAuth 2.0 | Contacts, companies, deals, accounts |
| Zendesk | OAuth 2.0 | Tickets, users, organizations |
| Asana | OAuth 2.0 | Tasks, projects, workspaces |
| Monday.com | OAuth 2.0 | Boards, items, updates |
| Notion | OAuth 2.0 | Pages, databases, search |
| Confluence | OAuth 2.0 | Pages, spaces, search |
| Shopify | OAuth 2.0 | Products, orders, customers, inventory |
| Stripe | API Key | Customers, payments, subscriptions |
| iCloud | Credentials | Email, contacts, calendar |
| Nextcloud | Credentials | Files, calendar, contacts |
Most integrations use standard OAuth 2.0. Stripe uses an API key (prefixed with sk_), and iCloud and Nextcloud use direct credentials.
Permissions by provider
When you connect a service, Thallus requests only the scopes it needs. Here are the detailed permissions for the most commonly connected services:
Slack
Slack uses bot-level scopes for most operations and one user-level scope for search:
Bot scopes: channels:history, channels:read, chat:write, groups:history, groups:read, im:history, mpim:history, reactions:read, reactions:write, users:read, users:read.email, app_mentions:read, team:read
User scope: search:read — required for searching messages across the workspace
Jira
| Scope | Description |
|---|---|
read:jira-work |
Read issues, projects, boards, sprints |
write:jira-work |
Create and update issues, add comments |
read:jira-user |
Read user profiles and assignments |
offline_access |
Refresh tokens for persistent access |
Microsoft 365
| Scope | Description |
|---|---|
Mail.Read |
Read Outlook emails |
Mail.Send |
Send emails |
Calendars.ReadWrite |
Read and create calendar events |
Contacts.Read, Contacts.ReadWrite |
Read and manage contacts |
Files.Read.All |
Read OneDrive files |
Team.ReadBasic.All, Channel.ReadBasic.All |
Read Teams structure |
ChannelMessage.Read.All, ChannelMessage.Send |
Read and send Teams messages |
Other providers
| Provider | Scopes |
|---|---|
| Linear | read, write, issues:create, comments:create |
| GitHub | repo, read:user, user:email |
| HubSpot | crm.objects.contacts.read/write, crm.objects.companies.read/write, crm.objects.deals.read/write, crm.objects.owners.read, oauth |
| Salesforce | api, refresh_token, offline_access |
| Zendesk | read, write |
| Asana | default (full access) |
| Monday.com | boards:read/write, updates:read/write, users:read, workspaces:read, me:read |
| Confluence | read:confluence-content.all, write:confluence-content, read:confluence-space.summary, read:confluence-user, search:confluence, offline_access |
| Shopify | read/write_products, read/write_orders, read/write_customers, read/write_draft_orders, read/write_inventory |
Notion uses page-based permissions instead of scopes — you select which pages Thallus can access during the authorization step.
Disconnecting
To disconnect an integration, go to the Integrations page and click Disconnect next to the connected service. This:
- Removes stored tokens — The encrypted access and refresh tokens are deleted
- Invalidates availability cache — The agent immediately becomes unavailable
- Removes from planning — The planner no longer sees the agent as available
Disconnecting does not delete any data that was previously retrieved through the integration. Conversation history and prior agent results are preserved.
Webhook auto-provisioning
Some integrations automatically set up webhooks when you connect, enabling real-time event processing:
| Provider | Webhook Setup | Events |
|---|---|---|
| Jira | Automatic on connect | Issue created, updated, commented |
| Linear | Automatic on connect | Issue created, updated, commented |
| Shopify | Automatic on connect | Order, product, customer events |
| Stripe | Automatic on connect | Payment, subscription, customer events |
| Slack | App-level (pre-configured) | Messages, reactions, mentions |
| GitHub | App-level (pre-configured) | Push, PR, issue events |
| Monday.com | App-level (pre-configured) | Board and item changes |
Providers marked "Automatic on connect" create webhook subscriptions on the external service during the OAuth flow. Providers marked "App-level" use webhooks configured at the Slack/GitHub/Monday app level, so no per-user setup is needed.
Other integrations (Google, Microsoft 365, HubSpot, Salesforce, Zendesk, Asana, Confluence) don't currently use webhooks — they operate on-demand when an agent calls their tools.
Chat settings
For chat-capable integrations — Slack and Microsoft Teams — a chat toggle appears on the agent card after connecting. This controls whether the bot responds directly to @mentions and direct messages.
- Off (default) — The bot does not send chat replies. Incoming messages and mentions are still received and can trigger workflows, but no conversational response is sent back to the channel or DM.
- On — The bot responds to @mentions and direct messages with an AI-generated reply, in addition to any workflow processing.
The toggle only appears on Slack and Teams agent cards when the integration is connected. Other integrations (Jira, GitHub, etc.) do not have chat settings because they don't operate as conversational bots.
Troubleshooting
"Authorization failed" after clicking Connect
- Check that your organization's Thallus instance has the provider's OAuth credentials configured (client ID and secret)
- For Zendesk and Shopify, verify that the correct subdomain/shop URL is configured — these providers use subdomain-specific authorization URLs
Agent shows "Requires connection" after connecting
- The availability cache may not have invalidated yet. Try refreshing the page
- Check the Integrations page to confirm the status shows "Connected"
- If the connection succeeded but the agent still shows unavailable, the OAuth token may have been immediately revoked by the provider — try disconnecting and reconnecting
Token expired errors
Thallus automatically refreshes OAuth tokens using stored refresh tokens. If you see token expiration errors:
- The refresh token itself may have expired (some providers expire refresh tokens after extended inactivity)
- The user may have revoked access from the provider's side (e.g., Google Account → Security → Third-party access)
- Disconnect and reconnect the integration to get fresh tokens
Next steps
- Available Agents — See what each integration agent can do once connected
- Turning Agents On/Off — Fine-tune which tools are active after connecting
- Agent Access Control — Understand who can use which agents