Gamut

Connected Accounts

How connected accounts work in Superagent — OAuth-based access to SaaS APIs with a secure proxy that keeps tokens away from agents.

Connected accounts give your agents access to SaaS APIs like Gmail, GitHub, Slack, and Salesforce. Superagent handles the OAuth flow, stores credentials securely via Composio, and proxies all API requests so that agents never see the underlying tokens.

How the Secure Proxy Works

The proxy is the core security mechanism of connected accounts. Here is the request flow:

  1. Agent makes a request — The agent sends an HTTP request to Superagent's proxy endpoint, authenticated with a synthetic token unique to that agent.
  2. Token validation — The proxy verifies the synthetic token and confirms the agent is mapped to the requested account.
  3. Host allowlisting — The proxy checks that the target API host is in the allowlist for that provider. For example, a Gmail account can only reach gmail.googleapis.com and www.googleapis.com. Requests to any other host are rejected.
  4. Scope policy enforcement — The proxy matches the request method and path against the provider's scope map to determine which OAuth scopes the call requires. It then resolves the policy for those scopes (allow, review, or block). See Scope Policies.
  5. Token injection — If the request is allowed, the proxy fetches the real OAuth token from Composio and injects it into the Authorization header.
  6. Forward and stream — The request is forwarded to the upstream API. The response is streamed back to the agent.
  7. Audit logging — Every request is logged with the agent slug, account ID, toolkit, target host, path, HTTP method, status code, matched scopes, and policy decision.

At no point does the agent receive the real OAuth token. The synthetic token is only valid for proxy requests and is scoped to a single agent.

Composio Proxy Fallback

Some Composio configurations redact OAuth tokens (e.g., Composio-managed auth configs). When Superagent detects a redacted token, it automatically falls back to Composio's proxy execute API, which attaches the real credentials server-side. This fallback is transparent — the agent and the upstream API see the same behavior.

Adding a Connected Account

OAuth Flow

  1. Navigate to Settings > Connections or open an agent's Connections panel.
  2. Click Add Connection and select a provider from the directory.
  3. A popup opens with the provider's OAuth consent screen. Sign in and grant the requested permissions.
  4. On success, Superagent creates a local record of the account and attempts to fetch a display name (e.g., your email address for Google accounts, your username for Microsoft accounts).

The OAuth flow works in both the Electron desktop app (using a custom protocol callback) and the web interface (using an HTTP callback endpoint).

Display Names

After connecting, Superagent tries to fetch a user-specific display name from the provider. For Google accounts, it queries the userinfo endpoint to get your email address. For Microsoft accounts, it queries the Microsoft Graph /me endpoint. If the fetch fails, the provider's display name (e.g., "Gmail") is used as a fallback.

You can rename a connected account at any time by editing its display name in the connections list.

Supported Providers

Superagent supports 40+ OAuth providers organized into the following categories:

Google Workspace

Gmail, Google Calendar, Google Drive, Google Sheets, Google Docs, Google Slides, Google Meet, Google Tasks, YouTube

Microsoft

Outlook, Microsoft Teams

Communication

Slack, Discord

Developer Tools

GitHub, GitLab, Bitbucket, Sentry

Project Management

Notion, Linear, Confluence, Asana, Monday.com, ClickUp, Trello

CRM and Sales

HubSpot, Salesforce, Zendesk, Intercom

Cloud Storage

Airtable, Dropbox, Box

Social Media

LinkedIn, Instagram

Finance

Stripe, QuickBooks, Xero

Marketing

Mailchimp

Design

Figma

Scheduling and Forms

Calendly, Typeform

Video

Zoom

Account Status

Each connected account has one of three statuses:

  • Active — The OAuth connection is valid and the account can be used by agents.
  • Revoked — The user revoked access from the provider's side (e.g., removed the app from Google account settings). The account must be reconnected.
  • Expired — The OAuth token expired and could not be refreshed. The account must be reconnected.

Deleting an Account

When you delete a connected account, Superagent removes the local record and also calls Composio's API to delete the upstream connection. Any agent mappings to that account are automatically removed via cascade delete.

Related