Connecting Integrations

Supyagent Cloud lets your agents interact with third-party services through a single API key. This guide walks you through the complete setup process.

1. Create an Account

Sign up at supyagent.com using GitHub or Google OAuth. After signing in, you'll see your dashboard with the Integrations panel.

2. Connect a Provider

Click Connect next to any provider to begin the OAuth flow:

1. You are redirected to the provider's authorization page (e.g., Google, Slack, GitHub)
2. Review and approve the requested permissions
3. You are redirected back to the Supyagent dashboard
4. The integration status changes to Active

Each provider requests specific OAuth scopes. See the Providers section for per-provider details.

Available Providers

3. Get Your API Key

After connecting at least one integration:

1. Go to Settings > API Keys in the dashboard
2. Click Create API Key
3. Copy the key -- it starts with sk_live_
4. Store it securely (it is only shown once)

The API key authenticates your agent's requests to the Supyagent Cloud API. A single key provides access to all your connected integrations.

4. Configure Your Agent

Add the service configuration to your agent's YAML file:

name: assistant
description: "Agent with cloud integrations"

model:
  provider: anthropic/claude-sonnet-4-5-20250929

system_prompt: |
  You are a helpful assistant with access to Gmail, Slack, and GitHub.
  Use the cloud tools when the user asks about emails, messages, or code.

service:
  enabled: true
  url: https://app.supyagent.com

tools:
  allow:
    - "*"

Set the API key as an environment variable or in your supyagent config:

# Environment variable
export SUPYAGENT_SERVICE_KEY=sk_live_abc123...

# Or configure it globally
supyagent config set SUPYAGENT_SERVICE_KEY sk_live_abc123...

5. Verify the Connection

Start a chat and ask the agent about your connected services:

supyagent chat assistant

You: What emails do I have today?

The agent will use the cloud Gmail integration to fetch and summarize your recent emails.

Managing Integrations

Viewing Connected Services

From the dashboard, the Integrations page shows all connected providers with their status:

Token Refresh

OAuth tokens expire periodically. Supyagent automatically refreshes tokens when they expire, using the stored refresh token. This happens transparently -- your agent never sees expired token errors.

Disconnecting a Provider

Click Disconnect next to any provider on the dashboard. This:

• Revokes the OAuth token
• Removes stored credentials
• Disables the integration's tools for your agents

Managing Permissions

Each provider has granular permissions you can enable or disable:

Google
  Gmail
    [x] Read emails
    [x] Send emails
  Calendar
    [x] Read calendar
    [ ] Manage events    <-- disabled
  Drive
    [x] Read files
    [ ] Manage files     <-- disabled

Disabling a permission prevents your agents from using that capability, even if the OAuth scope was granted.

Using the CLI

Supyagent provides CLI commands for managing service connections:

# View available service tools
supyagent service tools

# Check connection status
supyagent service status

# Configure the service endpoint
supyagent config set SUPYAGENT_SERVICE_URL https://app.supyagent.com
supyagent config set SUPYAGENT_SERVICE_KEY sk_live_...

Security

• OAuth tokens are encrypted at rest using AES encryption in the database
• API keys are hashed with HMAC before storage -- the raw key is never stored
• Permissions are checked on every API call -- your agents can only access services you explicitly enable
• Usage is logged for every API call your agent makes through the cloud

What's Next

• Providers -- Per-provider setup guides and examples
• API Reference -- REST API documentation
• Inbox -- Event-driven processing with the AI inbox