Auth and tokens
Your server signs a token; the browser connects with it. No round trip.
Your server signs tokens with your project's secret key, so handing one out needs no call to Pulse. A token names a user, lists the channels they may join and expires; the browser client asks your server for a new one when it needs to.
Sign a token
| Option | Meaning |
|---|---|
user | An id, or { id, name, image }. Others see the name and image in presence. |
channels | Channel names or patterns the user may join, like orders:*. * matches any run of characters. |
publish | Patterns the browser may publish to; true means the same as channels. Leave it out and the browser only reads. |
ttlSeconds | How long the token lasts. Default 10 minutes. |
A token route
createTokenRoute turns that into a route handler for any Fetch API router (Next.js, Remix, Hono, a plain fetch handler). Decide who the caller is from your own session; return null to refuse.
In the browser
Point the provider at your route, or pass a function that returns a token. It's safe with server rendering: nothing touches the network during render, and a relative URL is resolved in the browser only.
When a token is refused
A bad, expired or out-of-scope token never reaches the channel: the connection closes with a code the client acts on.
| Code | Means | The client |
|---|---|---|
4401 | Missing, malformed, badly signed or expired | Fetches a new token and reconnects |
4403 | Valid, but not for this channel | Stops; the status becomes forbidden |
4400 | A bad channel name or resume point | Stops |
4429 | Far too many presence updates | Waits a minute, then reconnects |
4503 | The channel is full (5,000 connections) | Retries with backoff |
Keep the key secret
- The secret key signs tokens and publishes to any channel. Keep it on your server, in
PULSE_SECRET_KEY. - Keys belong to a project. Create and revoke them in the dashboard; a revoked key stops working within a minute.
- Server-side publishing doesn't need a token at all: see Events.
Letters, digits and _ - : . @ / =. Use the prefix for the kind of thing (orders:, room:, chat:) so token patterns stay simple.