---
search:
  tags:
    - Realtime
    - POST
seo:
  description: >-
    A short-lived credential for opening the realtime WebSocket from a context
    that… Reference for the POST /realtime/token endpoint in the TipPage
    Developer API.
sidebar:
  label: Mint a realtime handoff token
  badge: POST
title: Mint a realtime handoff token
type: openapi-operation
---
A short-lived credential for opening the realtime WebSocket from a context that shouldn't hold the API key. Send `{"data": {"token": "..."}}` as the first WebSocket message before it expires; the connection then behaves exactly like an API-key connection (channels come from the key's scopes at connect time, and the connection outlives the token). Daemons that hold the key can skip this endpoint and connect with `{"data": {"apiKey": "..."}}` directly. Requires a key with at least one realtime-capable scope. Guide: https://docs.tippage.com/api/realtime

`POST /realtime/token`

**Request body** (`application/json`)

- `expires_in` (integer) — Token lifetime in seconds (how long it can be used to connect).
- `groups` (string[]) — Narrow the token to a subset of the key's groups - so a broad key can hand out a token that only sees some of them. Every name must be a group the key's own scopes already grant (otherwise 403 \`group\_not\_granted\`); it can only narrow, never widen. Omit to grant everything the key allows.

Request body example:

```json
{
  "expires_in": 900,
  "groups": [
    "tts",
    "twitch"
  ]
}
```

**Responses**

- `200` — Connection details.
- `400` — \`groups\` was malformed or contained an unknown group name (\`bad\_groups\`).
- `401` — Missing or invalid credential (\`missing\_api\_key\` / \`invalid\_api\_key\`, or \`invalid\_token\` for an expired/revoked OAuth access token).
- `403` — The key has no realtime-capable scopes (\`no\_realtime\_scopes\`), or \`groups\` asked for one the key doesn't grant (\`group\_not\_granted\`).
- `429` — Rate limit exceeded - check the \`RateLimit-\*\` headers.

Response example, 200:

```json
{
  "url": "wss://ws.tippage.com",
  "token": "string",
  "expires_at": "2019-08-24T14:15:22Z",
  "channels": [
    "dev:t_abc123:tts",
    "dev:t_abc123:twitch"
  ]
}
```
