> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Linked accounts

> List the accounts shared with your app, select an account, and manage its access.

A linked account is one OnlyFans account. When an owner approves access, they choose the accounts and permissions to share with your app. OFAuth saves this approval as an authorization. Each Access request works with one linked account.

All routes on this page use an access token sent as `Authorization: Bearer <access_token>`. Each route returns only accounts shared through that token's authorization. No route lists accounts from all authorizations.

## Where linked account ids come from

| Source | When |
| - | - |
| `GET /v3/linked-accounts` | Any time you hold a valid access token. |
| `linked_account_id` and `linked_account_ids` in [account and access events](https://docs.ofauth.com/v3/api-reference/system-webhook-events.md#lifecycle-events) | When an authorization or account changes. |

The same OnlyFans account in Sandbox, Test, and Live has different ids.

## List linked accounts

```http theme={null}
GET https://api.ofauth.com/v3/linked-accounts
Authorization: Bearer <access_token>
```

| Query parameter | Description |
| - | - |
| `limit` | Page size, `1` to `100`. Defaults to `50`. |
| `cursor` | `next_cursor` from the previous page. |

```typescript TypeScript SDK theme={null}
import { OFAuthClient } from "@ofauth/onlyfans-sdk"

const client = new OFAuthClient({ accessToken: process.env.ACCESS_TOKEN! })
for await (const account of client.linkedAccounts.iterate({ limit: 100 })) {
  console.log(account.id, account.status)
}
```

```bash curl theme={null}
curl "https://api.ofauth.com/v3/linked-accounts?limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json theme={null}
{
  "data": [
    {
      "id": "conn_example123",
      "provider": "onlyfans",
      "provider_account_id": "123456789",
      "username": "creator",
      "display_name": "Creator Name",
      "status": "connected",
      "scopes": ["profile:read", "messages:read"],
      "granted_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

Accounts are ordered by `id`. A bad `limit` or `cursor` returns `400` `invalid_request`.

| Field | Description |
| - | - |
| `id` | Send this as `x-linked-account-id`. |
| `provider` | `onlyfans`. |
| `provider_account_id` | The stable OnlyFans user id. |
| `username` | Current OnlyFans username, or `null`. Can change. |
| `display_name` | Current OnlyFans display name, or `null`. Can change. |
| `status` | `connected`, `needs_reconnect`, or `disconnected`. |
| `scopes` | Permission names, such as `profile:read`, that the owner approved for this account. |
| `granted_at` | When the account was shared with this authorization. |

## Get a linked account

```http theme={null}
GET https://api.ofauth.com/v3/linked-accounts/{id}
Authorization: Bearer <access_token>
```

Returns one account with the fields shown above. An account ID that is not part of this authorization returns `404` `linked_account_not_found` with `recovery.action` `list_linked_accounts`.

## Remove a linked account

```http theme={null}
DELETE https://api.ofauth.com/v3/linked-accounts/{id}
Authorization: Bearer <access_token>
```

Removes this authorization's access to one account and returns `204`. The account itself, the rest of the authorization, and other apps' access are unaffected. Repeating the call succeeds. Your webhook destinations receive `linked_account.disconnected` with `reason: "developer_deleted"`.

To end the whole authorization instead, [revoke](https://docs.ofauth.com/v3/api-reference/link/tokens.md#revoke) its sessions.

## Reconnect a linked account

Use `client.linkedAccounts.createReconnect({ id, body: { redirect_uri, state } })` to create a short-lived journey for an account that needs reconnecting. Open the returned `url`, verify the app session and `state` on return, then read current account status. See [Handle account reconnects](https://docs.ofauth.com/v3/guides/reconnect.md).

## Linked account settings

Use the API to manage settings for each account, such as Vault+.

```http theme={null}
GET https://api.ofauth.com/v3/linked-accounts/{id}/settings
PATCH https://api.ofauth.com/v3/linked-accounts/{id}/settings
```

```json theme={null}
{
  "linked_account_id": "conn_example123",
  "vault_plus": { "enabled": true }
}
```

`PATCH` accepts `vault_plus.enabled`, `vault_plus.overrides`, or both, and returns the updated settings. Send only the settings you want to change:

```json theme={null}
{
	"vault_plus": {
		"enabled": true,
		"overrides": { "auto_cache_posts": true }
	}
}
```

Set an override field to `null` to use the integration setting again. Set `"overrides": null` to clear all account overrides. The [PATCH reference](https://docs.ofauth.com/v3/api-reference/linked-accounts/update-linked-account-settings.md) lists the supported settings.

* `PATCH` needs the `vault:write` scope on that account, or it returns `403` `missing_scope`.
* Vault+ must be on for the environment. Test accounts need a paid Developer plan (`403` `subscription_required`).
* Sandbox accounts always have Vault+ on. `PATCH` in Sandbox returns `409` `linked_account_settings_fixed`.
* If another request changes the settings at the same time, the API returns `409` `linked_account_settings_conflict` with `recovery.action` `retry`.

See [Vault+](https://docs.ofauth.com/v3/guides/media-storage.md).

## Linked account status

| Status | Meaning | What to do |
| - | - | - |
| `connected` | Usable. | Call Access normally. |
| `needs_reconnect` | The OnlyFans session is no longer usable. Your access remains. | Ask the owner to reconnect. Access calls return `linked_account_reconnect_required`. You receive `linked_account.reconnected` when it works again. |
| `disconnected` | The owner disconnected the account. | Stop calling Access for it. |

## Select a linked account

Send the linked account id on every Access and Vault+ call.

```http theme={null}
GET https://api.ofauth.com/v3/access/profile
Authorization: Bearer <access_token>
x-linked-account-id: conn_example123
```

Missing header: `403` `linked_account_required`. An account that is not part of this authorization: `403` `linked_account_not_granted`. See [Errors](https://docs.ofauth.com/v3/api-reference/errors.md).

## Several accounts per authorization

One authorization can cover several linked accounts, for example an agency that manages several creators. Save the account IDs under their `authorization_id`. Let the user choose which account to use. The access token works for every account in the authorization; only the header changes.

Keep your list current with [account and access events](https://docs.ofauth.com/v3/api-reference/system-webhook-events.md#lifecycle-events): `authorization.updated` reports added and removed accounts, and `linked_account.disconnected` reports a single removed account.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.