---
title: "Accounts"
description: "List, connect, disconnect and refresh the social accounts you publish to."
section: "API reference"
url: https://dravo.dev/docs/api/accounts
---
# Accounts

Accounts are the connected social profiles you target in a publish call. The
recommended way to connect is the interactive [OAuth flow](/docs/api/oauth);
manual registration is available for advanced BYOK setups.

## List accounts

#### `GET /v1/accounts`

List connected social accounts with keyset pagination and optional filters.

**Auth:** API key (`dra_…`) or dashboard JWT

| Field | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider` | query | string | no | Filter by provider. |
| `q` | query | string | no | Search on handle/metadata. |
| `limit` | query | int | no | 1 to 100 (default 50). |
| `cursor` | query | string | no | Pagination cursor. |

Response `200`: A page of accounts.

```json
{
  "items": [
    {
      "id": "acc_8f2c1d",
      "provider": "x",
      "handle": "@dravo",
      "health": "active",
      "connection_type": "oauth"
    }
  ],
  "next_cursor": null,
  "total": 1
}
```


## Connect an account

Register an account directly with credentials. For most users the OAuth flow is
simpler and safer.

#### `POST /v1/accounts`

Register a provider account manually with credentials (BYOK). For interactive connection use the OAuth flow instead.

**Auth:** API key (`dra_…`) or dashboard JWT

| Field | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider` | body | string | yes | instagram | facebook | x | linkedin | tiktok. |
| `platform_account_id` | body | string | yes | Account ID on the provider. |
| `handle` | body | string | no | Display handle. |
| `credentials` | body | object | yes | Must include access_token; provider-specific extras (page_id, ig_user_id, author_urn). |

Request:

```json
{
  "provider": "x",
  "platform_account_id": "1890123",
  "handle": "@dravo",
  "credentials": {
    "access_token": "…"
  }
}
```

Response `201`: Account connected.

```json
{
  "id": "acc_8f2c1d",
  "provider": "x",
  "health": "active"
}
```


## Disconnect an account

#### `DELETE /v1/accounts/{account_id}`

Disconnect a connected account.

**Auth:** API key (`dra_…`) or dashboard JWT

| Field | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `account_id` | path | string | yes | Account to disconnect. |

Response `204`: Disconnected. No content.


## Refresh a token

Force an OAuth token refresh. If the refresh fails, the account likely needs to
be reconnected.

#### `POST /v1/accounts/{account_id}/refresh`

Force an OAuth token refresh for an account.

**Auth:** API key (`dra_…`) or dashboard JWT

| Field | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `account_id` | path | string | yes | Account to refresh. |

Response `200`: Refreshed.

```json
{
  "id": "acc_8f2c1d",
  "health": "active",
  "token_expires_at": "2026-09-01T00:00:00Z"
}
```

Errors:

- `409`: Refresh failed; account may need to reconnect.