Bepaal wie verbinding maakt en zich abonneert met je bestaande sessieregels.
Lever privé-orderupdates, accountmeldingen en werkruimte-events aan browser- en mobiele clients zonder backend-inloggegevens in clientcode bloot te stellen. Je eigen auth-endpoint controleert de sessie van de aanroeper en ondertekent per verbinding abonnementen op private of presence-kanalen, terwijl end-to-end-versleuteling gevoelige payloads versleutelt voordat ze je server verlaten.
auth.ts
200 · ondertekend403 · Forbidden200 · ondertekend200 · ondertekend// Your endpoint. The only place the app secret lives.app.post("/bird/auth", async (req, res) => { const { connection_id, channel_name } = req.body; const user = await session(req); if (!mayJoin(user, channel_name)) return res.sendStatus(403); // Signs <connection_id>:<channel_name>[:<member_data>] with the app // secret, and adds shared_secret on an encrypted channel. res.json( await bird.realtime.authorizeChannel({ connectionId: connection_id, channelName: channel_name, memberData: JSON.stringify({ member_id: user.id, member_info: { name: user.name }, }), }), );});
POST/bird/auth
Antwoordinhoud
{ "auth": "d0e95a856ddc1b09d4c8:8f9a2c71e4…", "member_data": "{\"member_id\":\"u_42\",\"member_info\":{\"name\":\"Maya Chen\"}}" }
auth.ts
200 · ondertekend403 · Forbidden200 · ondertekend200 · ondertekend// Your endpoint. The only place the app secret lives.app.post("/bird/auth", async (req, res) => { const { connection_id, channel_name } = req.body; const user = await session(req); if (!mayJoin(user, channel_name)) return res.sendStatus(403); // Signs <connection_id>:<channel_name>[:<member_data>] with the app // secret, and adds shared_secret on an encrypted channel. res.json( await bird.realtime.authorizeChannel({ connectionId: connection_id, channelName: channel_name, memberData: JSON.stringify({ member_id: user.id, member_info: { name: user.name }, }), }), );});
POST/bird/auth
Antwoordinhoud
{ "auth": "d0e95a856ddc1b09d4c8:8f9a2c71e4…", "member_data": "{\"member_id\":\"u_42\",\"member_info\":{\"name\":\"Maya Chen\"}}" }
auth.ts
200 · ondertekend403 · Forbidden200 · ondertekend200 · ondertekend// Your endpoint. The only place the app secret lives.app.post("/bird/auth", async (req, res) => { const { connection_id, channel_name } = req.body; const user = await session(req); if (!mayJoin(user, channel_name)) return res.sendStatus(403); // Signs <connection_id>:<channel_name>[:<member_data>] with the app // secret, and adds shared_secret on an encrypted channel. res.json( await bird.realtime.authorizeChannel({ connectionId: connection_id, channelName: channel_name, memberData: JSON.stringify({ member_id: user.id, member_info: { name: user.name }, }), }), );});
POST/bird/auth
Antwoordinhoud
{ "auth": "d0e95a856ddc1b09d4c8:8f9a2c71e4…", "member_data": "{\"member_id\":\"u_42\",\"member_info\":{\"name\":\"Maya Chen\"}}" }
Geef clients een publieke sleutel
terwijl ondertekeningsgeheimen op je server blijven.
Een app op de Bird Realtime API scheidt de verbindingsgegevens van clients van de bevoegdheden van je backend. Browsers en mobiele apps openen WebSockets met een publieke app-sleutel die je veilig in clientbundels kunt opnemen, terwijl je backend het geheim bewaart waarmee events worden gepubliceerd en abonnementstokens worden ondertekend. Vraagt je beveiligingsbeleid om rotatie van inloggegevens, dan maak je een tweede sleutelpaar aan, rol je dat uit over je services en trek je het vorige paar in zonder actieve gebruikers te verliezen.
Bescherm verbindingen, kanalen en payloads op elke laag
Verifieer wie een socket mag openen, autoriseer bij welke kanalen ze aansluiten, versleutel gevoelige eventgegevens en ontzeg toegang zodra een sessie eindigt.
- 01
Ondertekende kanaalabonnementen.
Abonneert een browser- of mobiele client zich op een privé- of presence-kanaal, dan controleert je backend de sessie van de gebruiker en ondertekent een HMAC-SHA256-token dat gekoppeld is aan die specifieke verbindings-ID en kanaalnaam. Doordat de handtekening aan de socket-ID is gebonden, kan een token niet op een andere verbinding worden hergebruikt. Presence-handtekeningen leggen daarnaast de lididentiteit vast die in de room wordt getoond.
- 02
Geauthenticeerde WebSocket-verbindingen.
Omdat je publieke app-sleutel in clientcode staat, kan elke bezoeker proberen een inactieve WebSocket te openen. Schakel je geautoriseerde verbindingen in, dan moet een nieuwe socket zich binnen 30 seconden via je backend authenticeren, door in te loggen of door zich op een privékanaal te abonneren. Niet-geverifieerde sockets worden automatisch gesloten en tellen niet mee voor je verbindingsquotum.
- 03
End-to-end versleutelde payloads.
Voor gereguleerde of vertrouwelijke updates versleutelt de server-SDK event-payloads lokaal met een masterkey van 32 bytes die op je eigen infrastructuur blijft. Elk versleuteld kanaal leidt een eigen ontsleutelingssleutel af. Geef je een client toegang tot één vertrouwelijke stream, dan krijgt die dus geen toegang tot een andere. Tussenliggende servers zien onderweg alleen versleutelde tekst.
- 04
Sessies direct intrekken.
Logt een gebruiker uit, wijzigt die een wachtwoord of verliest die toegang tot de werkruimte, dan verbreekt één serveraanroep de verbinding van die lididentiteit op alle open browsertabbladen en mobiele apparaten. Clients behandelen de beëindiging als definitief in plaats van steeds opnieuw verbinding te maken, en je auth-endpoint kan nieuwe inlogpogingen weigeren zodra de sessie is ingetrokken.
Encrypted channels
Versleutel gevoelige payloads voordat ze je server verlaten.
Configureer een masterkey van 32 bytes in de server-SDK om vertrouwelijke events binnen je eigen proces te versleutelen voordat je ze publiceert. Bird routeert de versleutelde envelop naar abonnees, en je autorisatie-endpoint levert de afgeleide ontsleutelingssleutel van het kanaal aan goedgekeurde browserclients. Je kunt versleuteling ook combineren met caching van het laatste event, zodat nieuw verbonden clients de nieuwste status als versleutelde tekst ontvangen. Houd kanaal- en eventnamen wel generiek, want routeringsmetadata blijft onversleuteld.
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY!,
realtime: {
key: process.env.BIRD_REALTIME_KEY,
secret: process.env.BIRD_REALTIME_SECRET,
// 32 random bytes, yours alone. Never sent to Bird.
encryptionMasterKey: process.env.BIRD_REALTIME_MASTER_KEY,
},
});
// Sealed in your process. The edge forwards ciphertext.
await bird.realtime.publish(APP_ID, {
event: "order.updated",
channels: ["private-encrypted-orders"],
data: { order_id: "ord_123", status: "shipped" },
});
Isoleer tenantstreams en valideer status op je server.
Verbindingsauthenticatie en kanaalautorisatie regelen verschillende delen van toegangsbeheer. Geautoriseerde verbindingen verplichten blokkeert anonieme sockets, terwijl private en presence-kanalen bepalen welke ingelogde gebruiker of tenant een specifieke stream kan lezen. Houd klantspecifieke updates op privékanalen die je auth-endpoint verifieert, gebruik client-to-client-events voor tijdelijke UI-signalen zoals typindicatoren en stuur statuswijzigende acties via je backend.
Leg verkeer vast in een regio en isoleer omgevingen per app.
Kies een vaste regio wanneer je een Realtime-app aanmaakt, zodat WebSocket-verbindingen en gepubliceerde events dicht bij je gebruikers blijven, ook als de thuisregio van je werkruimte elders ligt. Elke app draait in een eigen geïsoleerde namespace met aparte inloggegevens en quota. Met aparte apps voor development, staging en productie houd je testbroadcasts dus buiten live klantkanalen.
Implementatiegidsen voor je backend.
Volg kanalen autoriseren voor het formaat van het webhookverzoek en de ondertekeningshelpers van de SDK. Lees geautoriseerde verbindingen verplichten om de verbindingshandshake van 30 seconden af te dwingen, versleutelde kanalen om masterkeys en sleutelrotatie te configureren, en verbindingen van leden beëindigen om gebruikersaanmelding en verbreken op afstand in te richten.
Blijf bouwen
met Realtime.
Combineer kanaalautorisatie met live presence, statuscaching en backend-webhooks met dezelfde app-inloggegevens.
Channels
Routeer publieke broadcasts, privéstreams, versleutelde payloads en gecachete status op kanaalprefix.
→Presence
Toon wie online is op tabbladen en apparaten, volg wie vertrekt en stuur individuele gebruikers direct een bericht.
→Webhooks
Start backend-workflows wanneer kanalen actief worden, leden vertrekken of een cache moet worden opgewarmd.
→Schaal zonder controle te verliezen.
Separate production and sandbox traffic into dedicated workspaces, scope API keys to the exact channels each service or agent needs, and track permission changes in the audit log.