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

# Connect X

> POST /v1/platform-users/x/connect and /x/disconnect: let a platform user connect their X account, or remove it.

A platform user can connect their X account. It adds the X profile with follower counts to the [user object](https://docs.cabalspy.xyz/cabalspy-id/platform-users-get.md#response) and is required for the [KOL badge](https://docs.cabalspy.xyz/cabalspy-id/platform-users-kol.md).

## Connect

`POST /v1/platform-users/x/connect`

Returns an `authorize_url`. Send the user there, in a new tab or a redirect. They authorize with X and come back to your `return_url`. The URL is valid for 10 minutes and can be used once.

When the connection succeeds, you receive the `platform_user.x_connected` [webhook](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md#white-label-events) and the user object shows `x`.

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id.

**return\_url** `string` *required*

Where the user goes back after X. Must be on one of your instance's verified domains, registered origins or redirect URIs (https), or `http://localhost`.

```bash cURL theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/platform-users/x/connect" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_8412", "return_url": "https://app.example.com/profile"}'
```

```python Python theme={null}
import requests

r = requests.post("https://api-id.cabalspy.xyz/v1/platform-users/x/connect",
                  json={"external_id": "user_8412", "return_url": "https://app.example.com/profile"},
                  headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["data"]["authorize_url"])
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/platform-users/x/connect", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ external_id: "user_8412", return_url: "https://app.example.com/profile" }),
});
const { data } = await res.json();
// redirect the user to data.authorize_url
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "external_id": "user_8412",
    "authorize_url": "https://id.cabalspy.xyz/p/x/Kq8vN2...",
    "expires_at": "2026-10-26T08:14:11Z"
  },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-10-26T08:04:11Z" }
}
```

## Disconnect

`POST /v1/platform-users/x/disconnect`

Removes the user's X account. A user with the KOL badge cannot disconnect X, the badge belongs to the X account.

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id.

```bash theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/platform-users/x/disconnect" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_8412"}'
```

```json Response theme={null}
{
  "success": true,
  "data": { "external_id": "user_8412", "disconnected": true },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-10-26T08:20:00Z" }
}
```

`disconnected` is false when the user had no X account.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | external\_id or return\_url missing. |
| 400 | invalid\_return\_url | return\_url is not on one of your instance's sites. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 404 | platform\_user\_not\_found | No user with this id in your instance. |
| 409 | account\_claimed | The person claimed the account and manages it themselves. |
| 409 | kol\_badge | Disconnect: the user has the KOL badge. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


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