Publish events to browsers with PubSub

Messagingreal-time browser events (PubSub)

A PubSub token grants read or write on named channels for a number of minutes. Your server mints one per member, and decides who may write. The browser never holds the project API token.

pubsub

The claim

The vendored REST spec’s POST /api/pubsub/tokens requires two fields. ttl is “The maximum time, in minutes, for which the access token will be valid. Between 1 and 43,200 (30 days)“. channels is “User-defined channel names. Each channel is an object with read and/or write properties”. It also takes member_id, “The unique identifier of the member”, and state, “An arbitrary JSON object available to store stateful application information in”. It answers with a token. So the token is where the permissions live: a reader’s token names the channel with read true and write false, and a publisher’s has write true. The SDK wraps the call as client.pubsub.create_token.

How it works

def reader_token(member_id):
    return client.pubsub.create_token(
        ttl=TOKEN_TTL_MINUTES, member_id=member_id,
        channels={CHANNEL: {"read": True, "write": False}},
        state={"role": "reader"})

@app.post("/pubsub/token")
def token():
    body = request.get_json(force=True)
    member_id = body.get("member_id")
    if not member_id:
        abort(400)
    wants_write = body.get("role") == "publisher"
    has_key = bool(BOARD_KEY) and request.headers.get("X-Board-Key") == BOARD_KEY
    if wants_write and not has_key:
        abort(403)
    minted = publisher_token(member_id) if wants_write else reader_token(member_id)
    return jsonify({"token": minted["token"], "channel": CHANNEL})

What the platform receives, for a reader and then for the board:

POST /api/pubsub/tokens
{"ttl": 60, "member_id": "dana",
 "channels": {"workshop-board": {"read": true, "write": false}}, "state": {"role": "reader"}}

POST /api/pubsub/tokens
{"ttl": 60, "member_id": "board-1",
 "channels": {"workshop-board": {"read": true, "write": true}}, "state": {"role": "publisher"}}

The route hands the browser the minted token and the channel name, and nothing else. The browser asks for a role; the server decides whether it gets it. A request that asks to publish must carry the board’s key in X-Board-Key, a secret only the board process holds. The server refuses a request without it with 403 rather than downgrading it. Replace the header check with your own session check when you have sign-in.

Limitations

You prove the tokens and the route. Whether a subscribed browser receives a publish is the Browser SDK’s and the platform’s side. The token gates who may publish; it does not deliver anything by itself.

state is yours to define. The spec only says it must be valid JSON with a size limit.

What to change first

Give the reader’s channel write true and run the verifier. The reader body assertion fails. A customer’s phone that can write to the board is the bug this split of two token shapes exists to prevent.

Where this sits

Push events from a voice AI agent to the browser Let a browser dial your agent with no dashboard setup

python/app.py

"""Publish events to browsers with PubSub.

The token is the part your server owns. The vendored REST spec's
`POST /api/pubsub/tokens` requires `ttl`, "The maximum time, in minutes, for
which the access token will be valid. Between 1 and 43,200 (30 days)", and
`channels`, "User-defined channel names. Each channel is an object with `read`
and/or `write` properties." It takes an optional `member_id` and a `state`
object, and answers with a `token`. A browser that holds a token with `read`
on a channel subscribes to it; a publisher holds one with `write`. Your server
never hands out the project API token, and it decides per channel who reads
and who writes.

Written against signalwire-sdk 3.0.1 (RestClient.pubsub). The subscribe and
publish calls are the Browser SDK's, outside this recipe.
"""
import os

from dotenv import load_dotenv
from flask import Flask, abort, jsonify, request
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# RestClient() reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN /
# SIGNALWIRE_SPACE from the environment (signalwire/rest/client.py).
client = RestClient()

CHANNEL = os.getenv("CHANNEL", "workshop-board")
TOKEN_TTL_MINUTES = int(os.getenv("TOKEN_TTL_MINUTES", "60"))
# Only the board process holds this. A browser may ask to be a publisher; it
# gets a publisher token only if it also presents this key, and browsers do
# not have it. Replace the header check with your own session check when you
# have sign-in.
BOARD_KEY = os.getenv("BOARD_KEY")


def reader_token(member_id):
    """A browser's token: read on the channel, nothing else."""
    return client.pubsub.create_token(
        ttl=TOKEN_TTL_MINUTES, member_id=member_id,
        channels={CHANNEL: {"read": True, "write": False}},
        state={"role": "reader"})


def publisher_token(member_id):
    """The board's token: write as well as read."""
    return client.pubsub.create_token(
        ttl=TOKEN_TTL_MINUTES, member_id=member_id,
        channels={CHANNEL: {"read": True, "write": True}},
        state={"role": "publisher"})


app = Flask(__name__)


@app.post("/pubsub/token")
def token():
    """The server decides the role; the platform token then carries it."""
    body = request.get_json(force=True)
    member_id = body.get("member_id")
    if not member_id:
        abort(400)
    wants_write = body.get("role") == "publisher"
    has_key = bool(BOARD_KEY) and request.headers.get("X-Board-Key") == BOARD_KEY
    if wants_write and not has_key:
        abort(403)  # asked to publish without the key: refused, not downgraded
    minted = publisher_token(member_id) if wants_write else reader_token(member_id)
    return jsonify({"token": minted["token"], "channel": CHANNEL})


if __name__ == "__main__":
    app.run(port=int(os.getenv("PORT", "8080")))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # then edit .env: credentials, CHANNEL, TOKEN_TTL_MINUTES, and a random BOARD_KEY
python app.py

Then, from a page you serve:

curl -X POST http://localhost:8080/pubsub/token -H 'Content-Type: application/json' \
     -d '{"member_id": "dana"}'

The browser side is the Browser SDK’s PubSub client: it takes the token, subscribes to the channel, and receives what a publisher sends. That client is outside this recipe; the token it needs is what this recipe mints.

Verify it

No network, no account.

cd ..                     # back to the recipe folder
python verify.py

The verifier swaps the SDK’s HTTP layer for a recorder and drives the Flask route with its test client. It asserts the following.

reader_token and publisher_token each make one POST to the documented PubSub tokens path
the reader body is exactly ttl 60, the member id, the channel with read true and write false, and a state
the publisher body is the same shape with write true
the spec requires exactly ttl and channels, and describes ttl in minutes with the 43,200 bound
the spec describes channels as objects with read and/or write, documents member_id and state, and answers with token
the route returns exactly the token and the channel name, and mints a reader by default
the route mints a publisher only for a request carrying the board’s key, and the two route bodies carry their own member ids in full
the server refuses a request that asks to publish without the key, or with the wrong key, with 403, and mints nothing
the server refuses a request without a member id with 400 and mints nothing, and no request carries the API token

Report an issue