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

# Issue realtime token

> Mint a short-lived Supabase Realtime token so a channel client can subscribe to private storefront broadcasts.

Issues a 5-minute JWT signed with the project JWT secret. The token is `role: anon` with workspace claims (`merchant_id`, `env`) plus `customer_id`. Use it with the publishable key returned in the same payload to join the private broadcast topics.

> [!NOTE]
>
> Requires a Fire spark access token obtained through [token
> exchange](https://firespark.cloud/docs/storefront-api/oauth/exchange/post.md).

The optional body accepts the same scope fields as [Get menus](https://firespark.cloud/docs/storefront-api/menus/get.md). Workspace topic membership is `sf:{merchant}:{env}` (menus and availability). Order updates go on the customer topic `sf:{merchant}:{env}:c:{customer_id}`. Clients should ignore events whose payload scope does not overlap their current menu scope.

## Request

```bash theme={null}
curl -X POST "https://firespark.cloud/api/storefront/v1/realtime/token" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"downtown","channel_id":"kiosk","fulfillment_id":"dine-in"}'
```

## Response

| Field | Description |
| - | - |
| `access_token` | Short-lived JWT for `setAuth` on the Realtime client. Expires in 300 seconds. |
| `expires_in` | Always `300`. Refresh before expiry. |
| `url` | Supabase project URL. |
| `key` | Publishable key. Safe to embed; RLS and the short token limit access. |
| `topic` | Private channel name for this merchant workspace. |
| `customer_topic` | Private channel for this customer's order events (`…:c:{customer_id}`). |

## Events

| Event | When |
| - | - |
| `menu.changed` | A menu sync finished as latest and replaced live menu rows. Payload is the published scope (`fulfillment_id`, `store_id`, `channel_id`, `brand_id`). |
| `availability.changed` | Merchant availability or release rules were saved. Payload is `{ merchant_id }`. Intended for kiosk clients. App and web should refetch preferences on focus instead of opening a realtime connection. |
| `payments.changed` | A payment method was created, edited, or deleted. Payload is `{ merchant_id }`. Intended for kiosk clients. |
| `fulfillments.changed` | A fulfillment was created, edited, or deleted. Payload is `{ merchant_id }`. Intended for kiosk clients. |
| `order.changed` | The customer's order fulfillment advanced, paused, failed, or reached a terminal. Fires after each node finishes its work (callbacks included), not when the order enters the node. Payload includes `checkout_state`, `run_status`, `callbacks[]` (full callback `response` / `errors`), and `error`. Subscribe with `realtime.listenOrder({ orderId })` on `customer_topic`. On every `SUBSCRIBED` (including reconnect) the SDK fetches [Get order fulfillment](https://firespark.cloud/docs/storefront-api/orders/\[id]/fulfillment/get) and delivers that snapshot through the same `on.changed` handler. See [Fulfillment workflows](https://firespark.cloud/docs/guides/fulfillment-workflows.md). |


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