Identity & Sync Groups

​

Ablo does not do auth

​

What a sync group is

• the unit of fan-out — a confirmed write to a row publishes a delta to every participant subscribed to that row’s sync group(s), and
• the unit of access — a participant receives a row’s deltas only if the row’s sync group is in their allowed set.

​

Declare it, end to end

// 1. src/ablo/schema.ts — map identity → groups, and anchor each model to a group
import { defineSchema, identityRole, relation, model, z } from '@abloatai/ablo/schema';

export const schema = defineSchema(
  {
    // A scope root: its rows form the group `deck:<id>` (kind from `groups.root`).
    // Tenant isolation defaults to a row-local `organization_id` column, so no
    // `policy` is needed here.
    decks: model(
      { title: z.string(), status: z.enum(['draft', 'published']) },
      {},
      { groups: { root: 'deck' } },
    ),
    // A child: it has no group of its own; it inherits its deck's group via the
    // `parent` edge. A write to a slide reaches everyone viewing the deck.
    slides: model(
      { deckId: z.string() },
      { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
      {},
    ),
  },
  {
    // Each role is pure data: a `kind` (the group prefix) and the identity
    // `source` field to read. No closures — so the schema stays JSON-serializable.
    identityRoles: [
      identityRole({ kind: 'org', source: 'organizationId' }),
      identityRole({ kind: 'user', source: 'userId' }),
      identityRole({ kind: 'team', source: 'teamIds', multi: true }),
    ],
  },
);

// 2. app/providers.tsx — a HUMAN gets their full org / team scope.
// teamIds is set on the client you build (Ablo({ schema, teamIds: user.teamIds })),
// not passed to the provider; the provider just takes that client.
<AbloProvider client={ablo} userId={user.id}>
  {children}
</AbloProvider>

// 3. an AGENT run inherits its user, narrowed to the entities in play.
// You narrow at SESSION-MINT time: your backend calls `sessions.create` with the
// agent's allowed `syncGroups`, built from each model's scope via the
// `syncGroup(kind, id)` helper — never a hand-built `deck:<id>` string. The agent's
// runtime then connects with the minted token.
const session = await server.sessions.create({
  agent: { id: agentId },
  can: { Deck: ['read', 'update'] },
  syncGroups: [syncGroup('deck', deckId)], // floor: just the deck it's working on
});
// the agent runtime authenticates with the minted token
const ablo = Ablo({ schema, apiKey: session.token });

​

Two kinds of group — the whole mental model

• Membership groups — named after who you are: org:{id}, team:{id}, user:{id}. Produced from identity (identityRoles, Half 1). They’re standing and durable — they don’t change as you work.
• Entity groups — named after a thing: dataroom:{id}, deck:{id}, slide:{id}. Produced from a row’s id (a model’s entity scope, Half 2). They’re granular — one per record — and any participant can be pointed at a specific set of them.

One line: humans subscribe by who they are; agents subscribe by what they’ve been given.

your auth → identity { kind, userId|agentId, organizationId, teamIds }
          → identityRoles (schema) → allowed sync groups
          → participant receives deltas for rows in those groups

​

Your schema lives in a project; your users commit to it

await mintUserSessionKey({
  apiKey: platformKey,   // sk_ with the `ephemeral:mint-any-org` scope
  userId,
  organizationId,                  // DATA → this customer's org (RLS-isolated tenant)
  schemaProject: {                 // SCHEMA → the project that owns your schema
    organizationId: schemaOwnerOrgId,
    projectId: schemaProjectId,
  },
  ttlSeconds: 3600,
});

​

The two halves of scoping

​

Half 1 — identityRoles: identity → allowed groups

// src/ablo/schema.ts
import { defineSchema, identityRole, model, z } from '@abloatai/ablo/schema';

export const schema = defineSchema(
  {
    decks: model({
      title: z.string(),
      status: z.enum(['draft', 'published']),
    }),
  },
  {
    identityRoles: [
      identityRole({ kind: 'org', source: 'organizationId' }),
      identityRole({ kind: 'user', source: 'userId' }),
      // `multi: true` reads an array field — one `team:<id>` group per id.
      identityRole({ kind: 'team', source: 'teamIds', multi: true }),
    ],
  },
);

Single field per role. source reads one field. An agent doesn’t need its own role: it runs on behalf of a user and carries that user’s userId, so the user:{id} role above already covers it — see Agents are participants too.

​

Half 2 — per-model scope: row → group

decks: model({ title: z.string() }, {}, { groups: { root: 'deck' } });
// a deck row → group `deck:<id>`

slides: model(
  { deckId: z.string(), sourceSlideId: z.string().optional() },
  {
    deck: relation.belongsTo('decks', 'deckId', { parent: true }),  // ownership → inherit deck:<id>
    sourceSlide: relation.belongsTo('slides', 'sourceSlideId'),     // reference → NOT routed
  },
  {},  // default policy: row-local organization_id
);

Declare the parent edge — don’t infer it. Optionality is not a proxy for ownership: many parent FKs are optional (a root folder, an inbox task), and some required FKs are mere references. Containment is a fact only you know, so it’s declared, exactly as it is in OpenFGA/Zanzibar.

dataroomMember: model(
  { userId: z.string(), dataroomId: z.string() },
  {
    member: relation.belongsTo('users', 'userId'),
    room: relation.belongsTo('datarooms', 'dataroomId'),
  },
  { groups: { grants: { subject: 'member', scope: 'room' } } },
);

​

How identity reaches Ablo — the proxy model

1. Your ABLO_API_KEY lives only on your trusted server, scoped to your account. It signs your app’s relationship with Ablo. It must never reach a browser bundle — treat it like a Stripe secret key.
2. Your server authenticates the user with your own system. That’s the request that knows “this is user U, org O, teams [...]”.
3. Your server hands that authenticated identity to Ablo, and the browser talks to the realtime plane as an already-scoped participant. The browser never holds the API key and cannot widen its own scope — the security boundary is the identity your server vouched for, not anything the client asserts.
4. Ablo runs your identityRoles over that identity to compute the allowed sync groups, and the participant subscribes to exactly that set.

Why the proxy, not a client API key? A browser is a hostile runtime. If the client could name its own org or sync groups, any user could read another tenant’s data by editing a request. By keeping the API key server-side and deriving scope from the identity your server already authenticated, the trust boundary lands in the one place you control. This is the same reason Liveblocks resolves scope in prepareSession and Stripe mints ephemeral keys server-side.

​

Wiring the provider

// lib/ablo.ts
import Ablo from '@abloatai/ablo';
import { schema } from '@/ablo/schema';

// Build the client from the identity your server already resolved.
// teamIds → team sync groups via identityRoles.
export function makeAblo(user: { teamIds: string[] }) {
  return Ablo({
    schema,
    // The browser holds no secret — the `apiKey` resolver fetches the
    // short-lived session token your `/api/ablo-session` route minted, and the
    // client keeps it fresh before expiry.
    apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
    teamIds: user.teamIds,
  });
}

// app/providers.tsx
'use client';

import { useMemo } from 'react';
import { AbloProvider } from '@abloatai/ablo/react';
import { makeAblo } from '@/lib/ablo';

export function Providers({
  children,
  user, // { id, teamIds } — resolved server-side from YOUR auth
}: {
  children: React.ReactNode;
  user: { id: string; teamIds: string[] };
}) {
  const ablo = useMemo(() => makeAblo(user), [user.id]);
  return (
    <AbloProvider client={ablo} userId={user.id} fallback={<AppSkeleton />}>
      {children}
    </AbloProvider>
  );
}

​

Agents are participants too

agent authority = (triggering user's allowed set)    ← ceiling, inherited (on-behalf-of)
                ∩ (the model instances it touches)    ← floor, least privilege per run

// each scope-root model an agent edits forms a per-entity group
documents: model({ /* … */ }, {}, { groups: { root: 'document' } }),
decks:     model({ /* … */ }, {}, { groups: { root: 'deck' } }),

// agent run triggered by `user`, working on one document + one deck.
// Your backend mints the agent session narrowed to just the entities in play
// (the floor). Build each group from the model's scope with `syncGroup(kind, id)`.
const session = await server.sessions.create({
  agent: { id: agentId },
  can: { Document: ['read', 'update'], Deck: ['read', 'update'] },
  syncGroups: [syncGroup('document', documentId), syncGroup('deck', deckId)],
});
// identity (the ceiling) is inherited from the triggering user via your
// session-mint logic; the agent runtime connects with the minted token.
const ablo = Ablo({ schema, apiKey: session.token });

• Inherit the user, and no more — the OAuth on-behalf-of model: the agent’s reach is tied to the consenting user, never the org.
• Least privilege, just-in-time — scoped to the task’s entities, not standing org-wide access (the over-privilege pattern OWASP’s NHI Top 10 flags as the dominant agent risk).
• Dual-principal attribution — record both the executing agent and the triggering human.

​

Narrowing to specific entities

1. At session mint — syncGroups. When your backend mints a session, pass the exact groups it may subscribe to. This is the floor for a delegated agent (and the way to scope a focused page’s session):
   // an agent working across two decks and a document
   const session = await server.sessions.create({
     agent: { id: agentId },
     can: { Deck: ['read', 'update'], Document: ['read'] },
     syncGroups: [
       syncGroup('deck', deckA),
       syncGroup('deck', deckB),
       syncGroup('document', docId),
     ],
   });
   const ablo = Ablo({ schema, apiKey: session.token });
   
2. Automatically, on read or claim. Reading a row (retrieve/get/ claim.state) auto-enrolls the client in that row’s entity group (read-interest), and claim-ing it pins a write-intent subscription. So an agent’s reachable set accretes as it works — no extra subscribe call.
3. Explicitly, for presence — watch. To hold presence on a known set of rows and react to peers, use the WebSocket-only ablo.<model>.watch(ids, { ttl }) (it returns a participant handle with .peers). See Coordination.

groups.root is the schema model option, not a client setting. groups: { root: 'deck' } in model(...) declares a scope root (Half 2) — it names the group (deck:<id>) that the mechanisms above then subscribe to. There is no Ablo({ scope }) constructor option. The lifecycle filter on list() is a separate axis named state ('live' | 'archived' | 'all', GitHub’s open/closed/all), precisely so it doesn’t share the word.

Requested groups never grant. At connect, the server intersects the session’s syncGroups with what the identity is actually allowed (requested ∩ allowed). So syncGroups only ever narrows within a participant’s ceiling — an agent can’t reach a deck its capability doesn’t already permit, no matter what it passes. Smaller bootstrap, less fan-out, same server-enforced boundary.

​

How this compares — and the best practices it follows

• Server derives scope from authenticated identity — the server decides what a participant may read/write and the client cannot override it. This is Ablo’s proxy model. It’s the same shape as Supabase Realtime’s RLS-on-connect (policies evaluated at subscribe, cached for the connection), Liveblocks ID tokens (“Liveblocks checks the permissions for you” — recommended for production), and ElectricSQL proxy auth (a reverse-proxy sets shape params server-side before forwarding).
• Client proposes, server authorizes the exact request — the client names the room/shape and the server signs off, as in Pusher’s channel authorization endpoint, ElectricSQL gatekeeper auth, and Liveblocks access tokens. Ablo’s session-mint syncGroups is the narrowing half of this — but it can only ever shrink the server-derived set, never grow it.

1. The secret never reaches the client. Your ABLO_API_KEY lives only on a trusted server — exactly as Ably mandates (“never use API keys in client-side code; they don’t expire, so once compromised they grant indefinite access”) and PowerSync’s flow (app auth → backend mints a signed token → client connects with the token).
2. Trusted vs untrusted claims is the whole security argument. PowerSync draws the line precisely: token parameters are trusted and usable for access control; client parameters are not. In Ablo terms, the identity your server vouches for — and the session’s syncGroups, minted server-side — are the trusted claims that set scope; the userId prop is untrusted client input — convenient for app-owned fields, but never the boundary. This is why changing userId in the browser grants nothing.
3. Scope by a hierarchical naming convention, declared once. Ablo’s kind:id group naming (org:… / team:… from identityRoles, deck:… from a model’s scope) is the same idea as Liveblocks’ recommended room-id naming pattern (org:*, org:group:*) and Ably’s channel capabilities. Declaring the convention in one place — never composing scope strings in consumer code — is the practice all three enforce.
4. Attribution and presence ride the authenticated identity. Just as Pusher attaches channel_data to presence at auth time, Ablo’s participant identity (the one your server vouched for) is what powers presence and per-write attribution — not a value the client asserts after the fact.

​

See also

• Integration Guide — identityRoles, backing modes, and the full app path.
• React — the complete <AbloProvider> prop surface.
• API Keys — server-side keys for the public API.