> ## 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.

# Session

> POST /v1/platform-users/session: a 15-minute session token for one platform user, for the embeddable wallet verification UI.

Creates a short-lived session for one of your [platform users](https://docs.cabalspy.xyz/cabalspy-id/white-label.md). It lets the embeddable wallet verification UI act for exactly this user without your API key ever reaching the browser.

Create the session on your backend, pass `session` and `client_id` to your page, and create a new one when it expires. A session is valid for 15 minutes and only for your instance.

## Body

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

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

## Usage Example

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

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

r = requests.post("https://api-id.cabalspy.xyz/v1/platform-users/session",
                  json={"external_id": "user_8412"},
                  headers={"Authorization": "Bearer YOUR_KEY"})
s = r.json()["data"]
print(s["session"], s["expires_at"])
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/platform-users/session", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ external_id: "user_8412" }),
});
const { data } = await res.json();
// hand data.session and data.client_id to the page
```

## Response

**external\_id** `string`

Your id of the user.

**client\_id** `string`

Your Instance ID (`csid_...`), public.

**session** `string`

The session token, starts with `pvs_`. Treat it like a short-lived password for this user.

**expires\_at** `string`

When the session expires.

**expires\_in** `integer`

Lifetime in seconds, 900.

```json Response theme={null}
{
  "success": true,
  "data": {
    "external_id": "user_8412",
    "client_id": "csid_4f8a2c1e9b",
    "session": "pvs_Q2x1c3RlcnMgb2YgdG9rZW5zIGdvIGhlcmU...",
    "expires_at": "2026-10-26T08:19:11Z",
    "expires_in": 900
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-10-26T08:04:11Z"
  }
}
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | external\_id missing. |
| 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. |
| 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.