Integrations
List, inspect, and disconnect OAuth provider integrations for each connected account.
Integrations
Each connected account can have one integration per provider (e.g., one Google integration, one Slack integration). Integrations are created automatically when a user completes an OAuth connect flow and can be disconnected via the API.
List Integrations
GET /api/v1/accounts/:id/integrationsReturns all integrations for a connected account, including their enabled services.
curl https://app.supyagent.com/api/v1/accounts/550e8400-e29b-41d4-a716-446655440000/integrations \
-H "Authorization: Bearer sk_live_your_key_here"Response
{
"ok": true,
"data": {
"integrations": [
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"provider": "google",
"status": "active",
"connected_at": "2026-02-25T10:05:00.000Z",
"enabled_services": [
{ "service_name": "gmail.read", "is_enabled": true },
{ "service_name": "gmail.send", "is_enabled": true },
{ "service_name": "calendar.read", "is_enabled": true },
{ "service_name": "calendar.manage", "is_enabled": true },
{ "service_name": "drive.read", "is_enabled": true },
{ "service_name": "drive.manage", "is_enabled": true }
]
},
{
"id": "880e8400-e29b-41d4-a716-446655440003",
"provider": "slack",
"status": "active",
"connected_at": "2026-02-25T10:10:00.000Z",
"enabled_services": [
{ "service_name": "slack.read", "is_enabled": true },
{ "service_name": "slack.write", "is_enabled": true }
]
}
]
}
}Integration Fields
| Field | Type | Description |
|---|---|---|
id | string | Integration UUID |
provider | string | Provider identifier (google, slack, etc.) |
status | string | Connection status (see below) |
connected_at | string | ISO 8601 timestamp of when the integration was created |
enabled_services | array | List of granular service permissions |
Integration Statuses
| Status | Meaning |
|---|---|
active | Working — tokens are valid and ready to use |
pending | OAuth flow started but not completed |
expired | Token expired — will auto-refresh on next API call |
revoked | Access was revoked by the user or provider |
Enabled Services
Each integration has a set of granular service permissions. These are auto-enabled when the OAuth flow completes, based on the provider's permission registry. Each service controls access to specific API capabilities.
For example, a Google integration might have these services:
| Service | Description |
|---|---|
gmail.read | Read emails and threads |
gmail.send | Send and draft emails |
calendar.read | View calendar events |
calendar.manage | Create, update, delete events |
drive.read | View and download files |
drive.manage | Upload, create, and delete files |
Disconnect a Provider
DELETE /api/v1/accounts/:id/integrations/:providerRemoves a provider integration from a connected account. This deletes the stored OAuth tokens and disables all services for that provider.
curl -X DELETE https://app.supyagent.com/api/v1/accounts/550e8400-e29b-41d4-a716-446655440000/integrations/slack \
-H "Authorization: Bearer sk_live_your_key_here"Response
{
"ok": true,
"data": {
"deleted": true,
"provider": "slack"
}
}Errors
| Status | Error | Meaning |
|---|---|---|
| 404 | Not found | Account doesn't exist, or no integration for that provider |
After disconnecting, the user will need to complete a new connect session to re-authorize the provider.
Token Lifecycle
Automatic Refresh
OAuth tokens expire periodically (typically 1 hour for Google, varies by provider). Supyagent automatically refreshes tokens when they expire, using the stored refresh token. This happens transparently — your API calls never see expired token errors.
One Integration Per Provider
Each connected account can have at most one integration per provider. If a user re-connects a provider that's already connected, the existing integration is updated (upserted) with the new tokens. The old tokens are replaced.
Cascade on Account Deletion
When a connected account is deleted, all its integrations are automatically removed. Stored tokens are permanently deleted.
Checking Integration Status
You can view integrations either through the list integrations endpoint or by getting a single account, which includes integrations in its response.
A common pattern is to check integration status before making API calls:
// Check if the account has Google connected
const res = await fetch(
`https://app.supyagent.com/api/v1/accounts/${accountId}/integrations`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
);
const { data } = await res.json();
const google = data.integrations.find(i => i.provider === 'google');
if (!google || google.status !== 'active') {
// Prompt user to connect Google
const session = await createConnectSession(accountId, 'google');
// ... redirect to session.connect_url
}What's Next
- API Reference — Complete endpoint reference table
- React Components — Dashboard UI for partner management
Making API Calls
Route provider API calls to connected accounts using the X-Account-Id header — the core pattern for calling Gmail, Slack, GitHub, and other providers on behalf of your users.
API Reference
Complete endpoint reference for the Connected Accounts API — authentication, request formats, response shapes, and error codes.