Create, list, update, and delete connected accounts — sub-accounts that represent your end-users in the Supyagent platform.

Connected Accounts API

Connected accounts are lightweight sub-accounts that you create for each of your end-users. Each account has its own set of OAuth integrations, isolated from other accounts.

All endpoints require API key authentication and an active partner profile.

# All requests require this header
Authorization: Bearer sk_live_your_key_here

Create an Account

POST /api/v1/accounts

Creates a new connected account linked to your partner profile.

Request Body

Field	Type	Required	Description
`external_id`	`string`	Yes	Your internal identifier for the user (1-255 chars). Must be unique per partner.
`display_name`	`string`	No	Human-readable name (max 255 chars)
`metadata`	`object`	No	Arbitrary key-value data (stored as JSONB)

curl -X POST https://app.supyagent.com/api/v1/accounts \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user-456",
    "display_name": "Acme Corp",
    "metadata": { "plan": "enterprise", "region": "us-east" }
  }'

Response

{
  "ok": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "user-456",
    "display_name": "Acme Corp",
    "metadata": { "plan": "enterprise", "region": "us-east" },
    "created_at": "2026-02-25T10:00:00.000Z"
  }
}

Errors

Status	Error	Meaning
400	Validation error	Missing or invalid fields
403	`PARTNER_REQUIRED`	No active partner profile
409	Already exists	An account with this `external_id` already exists

List Accounts

GET /api/v1/accounts

Returns a paginated list of your connected accounts, ordered by creation date (newest first).

Query Parameters

Parameter	Type	Default	Description
`limit`	`number`	20	Results per page (max 100)
`offset`	`number`	0	Number of results to skip

curl "https://app.supyagent.com/api/v1/accounts?limit=10&offset=0" \
  -H "Authorization: Bearer sk_live_your_key_here"

Response

{
  "ok": true,
  "data": {
    "accounts": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "external_id": "user-456",
        "display_name": "Acme Corp",
        "metadata": { "plan": "enterprise" },
        "created_at": "2026-02-25T10:00:00.000Z"
      }
    ],
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}

Get an Account

GET /api/v1/accounts/:id

Returns a single connected account with its linked integrations.

curl https://app.supyagent.com/api/v1/accounts/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_live_your_key_here"

Response

{
  "ok": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "user-456",
    "display_name": "Acme Corp",
    "metadata": { "plan": "enterprise" },
    "created_at": "2026-02-25T10:00:00.000Z",
    "integrations": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "provider": "google",
        "status": "active",
        "connected_at": "2026-02-25T10:05:00.000Z"
      },
      {
        "id": "880e8400-e29b-41d4-a716-446655440003",
        "provider": "slack",
        "status": "active",
        "connected_at": "2026-02-25T10:10:00.000Z"
      }
    ]
  }
}

Errors

Status	Error	Meaning
404	Not found	Account doesn't exist or doesn't belong to your partner profile

Update an Account

PATCH /api/v1/accounts/:id

Updates the display_name and/or metadata of a connected account. At least one field is required.

Request Body

Field	Type	Required	Description
`display_name`	`string`	No	Updated display name (max 255 chars)
`metadata`	`object`	No	Replaces the entire metadata object

curl -X PATCH https://app.supyagent.com/api/v1/accounts/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Acme Corp (Enterprise)",
    "metadata": { "plan": "enterprise", "region": "eu-west", "seats": 50 }
  }'

Response

{
  "ok": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "user-456",
    "display_name": "Acme Corp (Enterprise)",
    "metadata": { "plan": "enterprise", "region": "eu-west", "seats": 50 },
    "created_at": "2026-02-25T10:00:00.000Z"
  }
}

Note: The metadata field is replaced entirely — it is not merged. Include all fields you want to keep.

Delete an Account

DELETE /api/v1/accounts/:id

Permanently deletes a connected account and cascades to all its integrations. OAuth tokens are removed.

curl -X DELETE https://app.supyagent.com/api/v1/accounts/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_live_your_key_here"

Response

{
  "ok": true,
  "data": {
    "deleted": true
  }
}

Warning: This action is irreversible. All integrations and stored tokens for the account will be permanently deleted. The user will need to re-authorize if the account is recreated.

The `external_id` Field

The external_id is your primary mapping key between your system and Supyagent. It must be unique per partner and can be any string up to 255 characters:

{ "external_id": "user-123" }
{ "external_id": "org_abc_user_456" }
{ "external_id": "tenant:acme:user:jane" }

Use whatever identifier makes sense in your system — a user ID, a composite key, or a slug. The external_id is returned in OAuth callback redirects, making it easy to reconcile which user just completed an OAuth flow.

What's Next

OAuth Connect — Initiate OAuth flows for connected accounts
Integrations — List and manage per-account integrations

Connected Accounts API

On this page