Private channels

A channel whose name starts with private- requires authorization from your backend in addition to the public app key. Your backend approves the caller for that channel and returns a signature computed with the app secret.

Use private channels for scoped data such as a customer's order updates, a tenant's dashboard, or one person's notifications.

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
  authEndpoint: "/bird/auth",
});

const orders = bird.subscribe("private-orders-4821");
orders.bind("order-updated", (data) => {
  console.log(data);
});

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1",
    authEndpoint: URL(string: "https://your-backend.example.com/bird/auth")
))

let orders = bird.subscribe("private-orders-4821")
orders.bind("order-updated") { data in
    print(data ?? "")
}

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
        authEndpoint = "https://your-backend.example.com/bird/auth",
    )
)

val orders = bird.subscribe("private-orders-4821")
orders.bind("order-updated") { data ->
    println(data)
}

Swift and Kotlin require an absolute authorization URL, while a browser client can use a same-origin path. Add your API's session token through authHeaders. The client includes these headers in each authorization request, including requests after a reconnect.

The client posts the connection ID and channel name to authEndpoint. The subscription completes only after the endpoint approves the caller and returns a valid signature. Authorizing channels defines the request, response, and string to sign.

Naming channels per user or per tenant

Put the resource scope in the channel name and verify it in your endpoint. A client can request any channel name, so your backend must prevent cross-customer subscriptions:

if (channel_name !== `private-orders-${user.accountId}`) {
  return res.sendStatus(403);
}

if channel_name != f"private-orders-{user.account_id}":
    return Response(status=403)

if channelName != "private-orders-"+user.AccountID {
	http.Error(w, "forbidden", http.StatusForbidden)
	return
}

if ($channelName !== "private-orders-{$user->accountId}") {
    http_response_code(403);

    return;
}

This comparison is the authorization decision. Never rely on unguessable channel names for access control.

What private channels support

Client events. When the app has client events enabled, a subscribed client can send client- events to the other clients on the channel without a round trip through your server. The edge rejects these on public channels.
Connection counting. With the app's connection counting and connection count events settings enabled, the client receives bird:connection_count for the channel.
Server publishing. Publishing from your server works exactly as it does for a public channel: name the channel in the channels array. No authorization applies to your server, which already holds the app secret.

Private channels have no member identity and no member events. If you need to know who is present, use a presence channel.

When a subscription is refused

A refused subscription arrives as bird:subscription_error. Common causes include a non-2xx response from your endpoint or a signature that does not match the request. See Authorizing channels for troubleshooting.

Next steps

Authorizing channels is the contract your backend implements.
Presence channels add member identity on top of the same authorization.
Excluding event recipients stops a client from receiving the event it caused.