Channel auth
Channel auth is the signed handshake that authorizes a client to subscribe to a private channel or presence channel. The application server inspects the user's session, decides whether the subscription is allowed, and returns an HMAC token. The WebSocket service verifies that token before accepting the subscription frame.
Why it matters
Channel auth is the bridge between the WebSocket service (which knows about connections and channels) and the application server (which knows about users, sessions, and permissions). The service does not need to know what a user is. The application does. Channel auth puts the authorization decision on the side that already has the answer.
This matters operationally. A team can change its auth model (rotate session strategy, add MFA, swap identity providers) without touching the WebSocket service. The service only ever sees a signed string. The signature is the contract.
It also matters for migrations. Because the channel auth endpoint lives in the application, and the signing algorithm is fixed by the Pusher protocol, the same auth route serves any protocol-compatible host. Migrations swap host and credentials; the auth route does not move.
How it works
The handshake has four steps.
-
Client connects via WebSocket. The service assigns a
socket_id. -
Client requests a subscription to
private-room-42. The SDK POSTssocket_idandchannel_nameto the configured auth endpoint. -
Application server runs its authorization logic. If allowed, it computes:
signature = HMAC-SHA256(app_secret, "{socket_id}:{channel_name}") auth = "{app_key}:{signature}"For presence channels it also includes
channel_data(a JSON object containinguser_idand optionaluser_info) and signs"{socket_id}:{channel_name}:{channel_data}"instead. The endpoint returns{ "auth": "...", "channel_data": "..." }. -
The SDK forwards the token in the
pusher:subscribeframe. The service recomputes the signature with its own copy of the secret and accepts the subscription if they match.
A minimal Laravel auth route is just:
Broadcast::channel('room-{roomId}', function ($user, $roomId) {
return $user->canJoin(Room::find($roomId));
});Laravel's BroadcastServiceProvider wires /broadcasting/auth to this routing layer automatically.
Related terms
- Private channel is the most common channel auth client.
- Presence channel extends channel auth with a
channel_datapayload. - Pusher protocol defines the signature format channel auth uses.
See also
- /learn/websockets-in-laravel for the Laravel BroadcastServiceProvider conventions.
- /migrate/pusher-to-vask-laravel for how the auth route stays unchanged across a host swap.
- What is channel auth?
- Channel auth is the server-side callback that authorizes a client to subscribe to a private or presence channel. The application server signs a token tying the user to a specific channel and socket connection, and the WebSocket service verifies that signature before accepting the subscription.
- What gets signed during channel auth?
- The string `socket_id:channel_name`, signed with HMAC-SHA256 keyed by the app secret. Presence channels also include `channel_data` (a JSON blob with user_id and optional user_info) in the signature payload.
- Where does the channel auth endpoint live?
- Inside the application server, alongside the rest of the auth-bound routes. Frameworks like Laravel ship a default endpoint at /broadcasting/auth. The route reads the session, decides whether the user is authorized to receive events on the requested channel, and returns the signed token.
