Requiring authorized connections

The app key is public. Anyone who can load your page can use it to open a connection and subscribe to public channels.

Authorized connections require each new connection to prove it is authorized within 30 seconds. The Realtime edge closes connections that do not authorize in time.

Require authorized connections

Enable Authorized connections for the app on the Realtime apps page. You can also set authorized_connections to true through the Realtime API. The setting applies to every connection that uses one of the app's keys.

Update clients to authorize before you enable the setting in production. Connections established before you enable it remain open, but later connections from older clients fail after the authorization timeout.

What counts as authorized

A new connection starts unauthorized. Either of these actions authorizes it:

A private or presence subscription succeeds. The client posts the connection ID to your authEndpoint, your backend signs it, and the edge verifies the signature. See Authorizing channels.
signin() succeeds. The client posts the connection ID to your memberAuthEndpoint and receives a signed member identity. See Terminating member connections for the complete sign-in flow.

Both routes prove the same thing: something holding the app secret vouched for this connection. Subscribing to a public channel proves nothing and does not authorize anything.

The public-channel-only case

A client that subscribes only to public channels does not normally contact your backend. After you require authorized connections, call signin() so the connection can authorize without a private subscription:

import { BirdRealtime } from "@messagebird/realtime";

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

await bird.signin();

const status = bird.subscribe("build-status");
status.bind("build-finished", (data) => render(data));

import BirdRealtime

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

try await bird.signin()

let status = bird.subscribe("build-status")
status.bind("build-finished") { data in
    render(data)
}

import com.bird.realtime.BirdRealtime
import com.bird.realtime.BirdRealtimeOptions

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

bird.signin() // suspending

val status = bird.subscribe("build-status")
status.bind("build-finished") { data ->
    render(data)
}

Call signin() once. The client signs in again after each reconnect because the identity belongs to the connection. Return 403 Forbidden from your member authorization endpoint when the caller must not connect.

If the app subscribes to a private or presence channel when it loads, the successful subscription already authorizes the connection.

What the client sees when it does not authorize

The edge closes the connection with code 4009 and the reason Connection not authorized within timeout. The clients do not retry codes in this range, so the connection enters the failed state.

bird.connection.bind("error", ({ code, message }) => {
  if (code === 4009) console.warn(message);
});

bird.onError { error in
    if error.code == 4009 { print(error.message) }
}

bird.onError { error ->
    if (error.code == 4009) println(error.message)
}

Code 4009 also identifies a member whose connections your backend terminated. Check the reason before choosing a login or signed-out state. See Terminating member connections and Connection lifecycle and reconnection.

Connections do not count toward the app's connection quota until they authorize.

Authorization scope

Requiring authorized connections controls who can hold a connection open. It does not replace authorization checks or change who can read a channel:

A public channel stays public to every authorized connection. If the events belong to one customer, use a private channel and check the channel name in your endpoint.
Anyone your own auth endpoints sign for is authorized, so a permissive endpoint hands out authorization as freely as the app key did.

Next steps

Authorizing channels is the signature your backend computes for private and presence subscriptions.
Private channels are the right tool when the events themselves belong to somebody.
Terminating member connections covers signin() and the other use of 4009.
Sending events to a member addresses an event to a signed-in identity instead of a channel.
Connection lifecycle and reconnection explains why 4009 is terminal.