Access Scopes - How They Work

Scopes follow the actor, not the room or the app. This one design choice makes multi-tenancy simple.

Core Concept: The Scope Follows the Actor

Access Scopes are not attached to rooms or apps. They are attached to actors. When an actor authenticates, the control plane resolves its scope and hands the broker two things: the scope's id and slug, and the list of topic patterns the actor may reach, every one of them already carrying the scope slug. From then on the broker rewrites the actor's plain app/room/topic subscriptions and publishes to app/scope/room/topic. The actor and the SDK do not need to know about scopes at all; the broker does.

This means you can add multi-tenant isolation to an existing application by creating scopes and assigning actors to them. No client code changes, no room duplication, no SDK upgrades.

Topic Namespace Diagram

The scope slug is inserted between the app slug and the room slug in the client-facing topic address:

Without Scope (unscoped actor)

app-slug / room-slug / topic-name
   |           |            |
   app         room         topic

With Scope (scoped actor)

app-slug / scope-slug / room-slug / topic-name
   |           |            |            |
   app       scope         room         topic

That four-segment form is what the broker matches against the actor's allowed patterns. Behind it, the broker maps each pattern to a distinct internal routing topic: {scopeId}/{roomId}/{topic} for a scoped actor, {roomId}/{topic} for an unscoped one. An actor subscribed to my-app-a3f9/client-acme/chat/messages therefore never shares a routing key with my-app-a3f9/client-beta/chat/messages, even though both name the same app, room and topic.

Isolation is enforced by the ACL, not by string matching alone. A scoped actor's allowed patterns all carry its own scope slug, so a subscribe or publish that names another scope, or that tries the three-segment unscoped form, matches nothing and is refused. Writing the four-segment form yourself works too, as long as it names the actor's own scope.

Data Model

Scopes are a project-level resource. They exist at the same level as apps and actors in the NoLag hierarchy:

Organization
  |-- Project
       |-- App (has rooms, topics)
       |-- Actor (has accessScopeId FK, nullable)
       |-- Access Scope (slug, name, description, metadata, isActive)

• An actor has an optional accessScopeId foreign key pointing to an Access Scope
• If accessScopeId is null, the actor is unscoped and uses the default topic namespace
• If accessScopeId is set, the actor is scoped and its topics include the scope slug

No SDK Changes Needed

The client SDKs never see the scope. @nolag/js-sdk, the Python SDK and the Go SDK subscribe and publish to app/room/topic (or through the fluent client.setApp(slug).setRoom(slug) context), and message handlers keep firing on the topic name you registered. All of the work happens in the platform:

• The control plane resolves the actor's scope at authentication and at every revalidation, and builds the actor's allowed patterns with the scope slug already in place.
• The broker stores the scope id and slug on the connection, rewrites app/room/topic to app/<scope>/room/topic on subscribe and publish, and maps that to a scope-specific internal topic. It also includes the scope (accessScopeId, slug, name) in webhook payloads, so a hydration or trigger endpoint can route to the right tenant without a lookup.
• Your client code is unchanged.

Key Rules

Next Steps

• Getting Started - create your first scope and assign actors
• Multi-Tenancy Patterns - real-world patterns for tenant isolation
• API Reference - complete endpoint documentation