Tus reglas de sesión deciden quién puede suscribirse.

No hay un modelo de permisos que configurar en Bird. Una suscripción privada o de presencia la aprueba un endpoint que tú escribes, usando la sesión que ya tienes, y firmada con un secreto que solo tus servidores guardan. Bird verifica la firma; tú decides la política.

Empezar Contactar con ventas

auth.ts

200 · signed

// 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 },
      }),
    }),
  );
});

auth.ts

200 · signed

// 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 },
      }),
    }),
  );
});

Una clave es pública. La otra no.

Todo se deriva de esa separación.

Cada app en el Bird Realtime API tiene una clave y un secreto. La clave está pensada para incluirse en el código del cliente; el secreto autentica las llamadas de tu servidor y firma las suscripciones, y se muestra una sola vez, al crearlo. Cualquiera que lo tenga puede publicar en tu app y falsificar una identidad de presencia, así que trátalo como una contraseña de base de datos. La rotación es aditiva en lugar de disruptiva: crea una segunda clave, despliégala y luego revoca la anterior.

Cuatro controles, cuatro preguntas

Quién puede suscribirse, quién puede mantener una conexión, quién puede leer un payload y quién sigue teniendo acceso.

01
Suscripciones firmadas.
El cliente envía su connection id y el nombre del canal a tu endpoint. Tú verificas al solicitante, rechazas con un 403 si no puede unirse, o devuelves una firma HMAC-SHA256 sobre el connection id y el nombre del canal, precedidos por la clave de la app. Como el connection id está en la firma, una aprobación cubre una sola conexión y no puede reproducirse en otra. Un canal de presencia también firma la identidad del miembro, y debe ser exactamente la cadena que devuelves: re-serializar el mismo objeto puede reordenar las claves e invalidar la firma.
02
Conexiones autorizadas.
La clave de la app es pública, así que cualquiera que pueda cargar tu página puede abrir un socket con ella. Activa las conexiones autorizadas y cada nueva conexión tiene 30 segundos para demostrar que algo con el secreto la avaló, mediante una suscripción privada o un inicio de sesión. Cualquier conexión que no lo haga se cierra con el código 4009, y las conexiones no autorizadas nunca cuentan contra tu cuota. Suscribirse a un canal público no demuestra nada y no autoriza una conexión.
03
Cifrado de extremo a extremo.
Un canal private-encrypted- se sella en tu servidor antes de que la solicitud salga de tu proceso, con una clave maestra de 32 bytes que nunca aparece en una solicitud a la API de Realtime. Cada canal deriva su propia clave, así que autorizar a un cliente en un canal cifrado no le permite leer otro. Bird no puede recuperar una clave perdida, y la rotación protege los payloads futuros, no los pasados.
04
Revocar el acceso de inmediato.
Un usuario que cerró sesión, una contraseña cambiada, una cuenta baneada: desconecta al miembro y cada conexión que esa identidad mantenga se cierra, en todos los dispositivos. Los clientes tratan ese cierre como terminal en lugar de reintentar, y tus propios endpoints dejan de firmar para ellos, así que no pueden volver.

Canales cifrados

Payloads que Bird no puede leer, en infraestructura que Bird opera.

Lee la guía de cifrado

El SDK del servidor detecta el prefijo del canal, deriva la clave de ese canal a partir de tu clave maestra y sella el payload localmente. El edge reenvía el texto cifrado y tu endpoint de autorización entrega la clave derivada solo a los clientes que aprueba. Dos limitaciones a considerar en el diseño: los nombres de canal y de evento viajan en texto claro, así que elige nombres que no revelen lo que estás protegiendo, y el cifrado no se puede combinar con presencia ni con eventos del cliente. El almacenamiento en caché es posible: un canal private-encrypted-cache- almacena su evento en caché sellado.

encrypted.ts

sealed locally

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" },
});

Lo que la autorización no hace.

Requerir conexiones autorizadas controla quién puede mantener un socket abierto. No cambia quién puede leer un canal: un canal público sigue siendo legible por toda conexión autorizada, así que los eventos que pertenecen a un cliente deben ir en un canal privado cuyo nombre tu endpoint verifica. Y como tus endpoints son la autoridad, un endpoint permisivo otorga acceso con la misma libertad que una clave filtrada. La misma honestidad aplica a los eventos del cliente, que el edge no valida: úsalos para señales y enruta todo lo autoritativo a través de tu servidor.

Dónde residen los datos.

Una app elige su región cuando la creas y la conserva de por vida, así que elige la más cercana a tus usuarios; la región de una app puede diferir de la región principal de tu espacio de trabajo. Las apps también son el límite de aislamiento: dos apps nunca ven los canales de la otra, y por eso una app por entorno es la forma correcta de mantener el tráfico de staging fuera de producción.

Profundiza en la documentación.

Autorización de canales tiene el contrato de solicitud y respuesta y la cadena exacta que firmar. Requerir conexiones autorizadas cubre la ventana de 30 segundos y el código 4009, canales cifrados cubre la generación y rotación de claves, y terminar conexiones de miembros es el flujo de inicio de sesión y desconexión.

El resto de Realtime

Una app, un par de claves. Explora las demás capacidades.

CanalesPúblicos, privados, de presencia, cifrados y con caché, todos seleccionados por el nombre.PresenciaQuién está en la sala, quién acaba de salir y cómo contactar a una persona directamente.WebhooksTu servidor se entera cuando un canal se llena, se vacía o falla su caché.PreciosConexiones y mensajes por plan, desde el nivel gratuito en adelante.Primeros pasosDel registro a tu primer evento publicado.Descripción general de Realtime APIEl producto completo: canales, presencia, seguridad, webhooks y los clientes.

Escala sin
perder el control.

Organiza equipos en espacios de trabajo, controla el acceso a la API y rastrea cambios en los registros de auditoría.

HarborOrganización

Espacios de trabajoProducciónSandbox

Agente de entrega

Clave de API · Equipo de Operaciones de clientes

Activo

PermisosAcceso

EmailLectura y escritura

SMSLectura y escritura

ALAlex Lee AdministradorPermisos actualizados

Registro de auditoría

Producción

Espacio de trabajo: Producción
Recurso: Agente de entrega
WhatsApp: Acceso de lecturaLectura y escritura

Completado

Explora Enterprise

Empieza con Realtime.
Construye en todos los canales con Bird.