ReferenceAsk
Back to Remy
Remy Reference/agent/events.grant
?

events.grant

Mints a subscribe token for an explicit list of channels, after your own authorization checks.
events.grant(channels, { ttlSeconds?, publish? }) → Promise<EventGrantResult>

Mints the token a client uses to subscribe, for an explicit list of channels named exactly (up to 100, no wildcards). Call it from one of your own methods and do the authorization check there first: the grant is the entire subscribe-side authorization, and the platform delivers the named channels to whoever holds the token. Return the result from your method and hand the token to the client.

Naming channels in the grant's publish list also lets the holder publish on them directly from the client, the fast path for ephemeral signals. Scope it tightly, since the browser-held token can inject events on those channels until it expires. The lifetime also sets the revocation window: a shorter TTL cuts off revoked access faster, at the cost of re-minting more often. Per-user channels with publish-time fan-out stop a removed member immediately, regardless of TTL.

Parameters
channels
string | string[]
RequiredThe exact channels this token may receive, up to 100. Whoever holds the token receives them, so do your authorization first.
ttlSeconds
number
Grant lifetime in seconds, clamped to between 60 and 3600 (default 900). This is also the stream's lifetime and your revocation window: at expiry the client re-mints through this method, re-running your checks.
publish
string | string[]
Channels the holder may also publish on, up to 20, the client-direct fast path for cursors, typing, and live strokes. Treat it as the browser-held credential it is: whoever holds the token can inject events on these channels until the TTL. Client events cap at 8k serialized and are rate-limited per grant.
The subscribe door is one of your methods
import { auth, events } from '@mindstudio-ai/agent';

export async function watchInbox() {
  auth.requireRole('member');                    // your checks first
  return await events.grant(`user:${auth.userId}`);
}