Identity

Realtime records an actor for writes such as publishing messages, joining rooms, updating presence, applying CRDT updates, and creating authorization tokens.

Resolve identity from request context

When an upstream gateway or middleware sets identity headers, Realtime can resolve the current user:

const live = realtime({
  name: "live",
  autoResolveUser: true,
})

app.use(live)

app.post("/rooms/:roomId/messages", async (request) => {
  const pathSegments = new URL(request.url).pathname.split("/")
  const roomId = pathSegments[2]
  return await live.room(roomId).publish({
    type: "message.created",
    data: await request.json(),
  })
})

The resolved actor is stored with the Realtime action:

{
  kind: "user",
  userId: "user_123",
  sessionId: "session_123",
  tenantId: "tenant_123"
}

Pass an explicit actor

Use explicit actors for background jobs, admin actions, imports, service events, or custom auth systems:

await live.room("project_123").publish({
  type: "deployment.finished",
  data: {
    deploymentId: "dep_123",
  },
  actor: {
    kind: "user",
    userId: "admin_123",
    tenantId: "tenant_123",
  },
})

Allow anonymous users

For public demos, temporary guests, or pre-login collaboration, enable anonymous actors:

const live = realtime({
  name: "live",
  allowAnonymous: true,
})

Anonymous actors are useful for visitor counters, public dashboards, and guest-first collaboration flows.

Require identity for private rooms

Keep allowAnonymous disabled for private rooms:

const live = realtime({
  name: "private",
  allowAnonymous: false,
})

Require identity before writing to private app data:

app.post("/documents/:documentId/updates", async (request) => {
  const pathSegments = new URL(request.url).pathname.split("/")
  const documentId = pathSegments[2]
  return await live.crdtRoom(documentId).applyUpdate({
    update: await request.json(),
  })
})

Issue room tokens

Use authorize() to create a short-lived room token:

app.post("/rooms/:roomId/token", async (request) => {
  const pathSegments = new URL(request.url).pathname.split("/")
  const roomId = pathSegments[2]
  return await live.room(roomId).authorize({
    ttlSeconds: 300,
  })
})

The result includes a token, expiration time, room identity, and actor.