Connected Accounts
Connected Accounts
Manage OAuth integrations on behalf of your end-users with the Connected Accounts API — a white-label integration layer for SaaS platforms.
Connected Accounts
The Connected Accounts API lets you manage third-party integrations on behalf of your users. Instead of each user signing up for Supyagent directly, you register as a partner, create connected accounts for your users, and run hosted OAuth flows to connect their services — all through your API key.
Use Cases
- SaaS platforms that need Gmail, Calendar, or Slack access for their users
- AI agent platforms that want to give each customer their own set of integrations
- Workflow automation tools that connect to third-party services on behalf of clients
- White-label solutions where the end-user never sees the Supyagent dashboard
How It Works
Your App Supyagent OAuth Provider
─────── ──────── ──────────────
│ │ │
│ 1. Create account │ │
│ POST /api/v1/accounts │ │
│─────────────────────────────>│ │
│ │ │
│ 2. Initiate connect │ │
│ POST /accounts/:id/connect │ │
│─────────────────────────────>│ │
│ │ │
│ 3. Redirect user to │ │
│ connect_url ─────────────│──────────────────────────────>│
│ │ │
│ │ 4. User authorizes │
│ │<─────────────────────────────│
│ │ │
│ │ 5. Exchange code for token │
│ │─────────────────────────────>│
│ │<─────────────────────────────│
│ │ │
│ 6. Redirect to your app │ │
│ ?status=success&provider=.. │ │
│<─────────────────────────────│ │
│ │ │
│ 7. Make API calls │ │
│ GET /api/v1/gmail/messages │ │
│ X-Account-Id: <external_id> │ │
│─────────────────────────────>│ 8. Use stored token │
│ │─────────────────────────────>│
│<─────────────────────────────│<─────────────────────────────│Key Concepts
| Concept | Description |
|---|---|
| Partner Profile | Your registration as a platform builder. Required to use the Connected Accounts API. |
| Connected Account | A sub-account representing one of your end-users. Identified by an external_id you control. |
| Connect Session | A time-limited OAuth session (30 minutes) that handles the authorization flow for a connected account. |
| Integration | A connected provider (Google, Slack, etc.) linked to a specific connected account. Tokens are encrypted and auto-refreshed. |
Supported Providers
All 14 OAuth providers are supported for connect sessions:
| Provider | Services |
|---|---|
| Gmail, Calendar, Drive, Docs, Sheets, Slides | |
| Slack | Channels, messages, users |
| GitHub | Repos, issues, pull requests |
| Discord | Servers, channels, messages |
| Microsoft | Outlook, Calendar, OneDrive |
| Profile, posts | |
| Twitter/X | Tweets, users |
| Notion | Pages, databases |
| HubSpot | Contacts, deals, companies |
| Jira | Projects, issues |
| Linear | Teams, issues, projects |
| Calendly | Event types, scheduled events |
| Salesforce | Contacts, opportunities |
| Pipedrive | Deals, contacts, activities |
Security
- OAuth tokens are encrypted at rest using AES encryption
- API keys are HMAC-hashed — the raw key is never stored
- PKCE + CSRF protection on all OAuth flows
- Connect sessions expire after 30 minutes
- Account isolation — each connected account has its own integrations with separate tokens
- Automatic token refresh — expired tokens are refreshed transparently
In This Section
- Quickstart — Register as a partner and connect your first account
- Code Examples — TypeScript, Python, and cURL examples for every operation
- Connected Accounts API — Create, list, update, and delete accounts
- OAuth Connect — Initiate and manage OAuth flows
- Making API Calls — The
X-Account-Idheader pattern for provider calls - Integrations — Manage per-account provider connections
- API Reference — Complete endpoint reference
- Usage & Billing — Pricing tiers, rate limits, and overage billing
- Testing & Development — Local dev setup and OAuth testing
- Troubleshooting — Error reference and debugging guide
- React Components — Dashboard UI components for partner management