How authentication works

Every connection to Folkways presents a token: a short-lived, signed pass that says which segment the connection belongs to, who it is and what it may do. There are two ways to get one.

Tokens signed by your backendCopy Anchor Link

 Your app                     Your backend                         Folkways node
    │  POST /api/realtime-token   │                                       │
    │  (with your login cookie)   │                                       │
    │ ──────────────────────────► │ checks the user is signed in,          │
    │                             │ signs a token with the private key     │
    │ ◄────────────────────────── │                                       │
    │            { token }        │                                       │
    │ ─────────────── connect with the token ───────────────────────────► │
    │                             │        checks the signature with the   │
    │ ◄──────────────────────────────────────── session ───────────────── │  public key

1. Your app asks your backend for a token, using your normal login (cookie or header).
2. Your backend checks the user and signs a token with the segment's private signing key. With @folkways/realtime/server this is one call, and it makes no network request.
3. The app connects with the token. The node checks the signature with the segment's public key, which it got from the dashboard.

The private key never leaves your backend, and nothing secret is ever sent over the network.

What a token containsCopy Anchor Link

A token is a standard JWT. rte.createToken() fills it in for you; if you sign tokens with another JWT library, use these fields:

PermissionsCopy Anchor Link

A token lists topic patterns and the operations allowed on them:

capabilities: [
  { topics: 'chat/>', ops: ['subscribe', 'publish'] },  // read and write every chat room
  { topics: 'typing/>', ops: ['subscribe', 'signal'] }, // see and send typing indicators
  { topics: 'scores/*', ops: ['subscribe'] },           // read scores only
]

An operation must be allowed by both the token and the topic's rule in the dashboard. If either says no, the node answers Forbidden.

Grant each user only what they need, for example chat/team-7/> instead of chat/> for a member of team 7. In your app, session.can('publish', 'chat/lobby') tells you whether to show a send button. The node still enforces every permission.

Lifetime and refreshCopy Anchor Link

Tokens live at most 15 minutes; createToken() makes them last 10 by default. You never handle expiry yourself:

• The SDK asks for a new token about a minute before the current one expires, and swaps it on the open connection without dropping subscriptions.
• If the node rejects a token, the SDK asks once more, with reason 'rejected'.
• A plain string token can't be refreshed: the connection closes with AuthExpired when it runs out. Use it only for tests.

Signing keysCopy Anchor Link

You add signing keys on the segment's Signing keys tab.

Rotating a key without downtime:

1. Add a new key with a new ID. Both keys work side by side.
2. Switch your backend to sign with the new key and its ID.
3. After 15 minutes (the longest a token can live), delete the old key.

Deleting a key also closes every connection that is still using a token signed with it, which is how you cut off access quickly if a key leaks.

Publishable keysCopy Anchor Link

A publishable key (rte_pk_…) is meant to be public: it ships inside your web page or app. The SDK trades it at the node for an anonymous, read-only token, so a copied key can never write to a topic or pose as a user. The worst it can do is read what your public page already shows.

• It can grant only subscribe and history, on the topics you chose when creating it.
• The segment must allow anonymous connections (Settings → Who can connect).
• You can pause, resume or revoke it on the Publishable keys tab. Pausing or revoking also closes the connections using it.

See Publishable keys.

Giving the SDK a tokenCopy Anchor Link

Pass exactly one of these options to new Folkways.Realtime():

// 1. Your token endpoint. The SDK POSTs { reason } and reads { token } or a plain-text token.
new Folkways.Realtime({ url, authUrl: '/api/realtime-token' });

// 2. Your own function, for custom requests or token caching.
new Folkways.Realtime({
  url,
  token: async ({ reason }) => {        // reason: 'initial' | 'expiring' | 'rejected'
    const res = await fetch('/api/realtime-token', { method: 'POST', credentials: 'include' });
    return (await res.json()).token;
  },
});

// 3. A publishable key, for read-only apps without a backend.
new Folkways.Realtime({ url, publishableKey: 'rte_pk_…' });

// 4. A fixed token string. It can't be refreshed: tests and scripts only.
new Folkways.Realtime({ url, token: 'eyJhbGciOi…' });

authUrl sends your page's cookies when the endpoint is on the same origin. For an endpoint on another domain, or to send a header such as Authorization, use authHeaders or the token function.

Sign-in and sign-outCopy Anchor Link

When the user signs in, signs out or switches account, give the client a new token source:

await client.updateToken(async () => fetchTokenForCurrentUser());

• Same identity (for example, new permissions): the connection and subscriptions stay.
• Different identity: the client reconnects as the new user, ends every subscription with IdentityChanged and wipes the previous user's local data.

To sign out completely, close the client and wipe its local data:

await client.close({ clear: true });

Catching a wrong segmentCopy Anchor Link

Pass the segment you expect to connect() to fail fast when, say, a staging token reaches production:

await client.connect({ segment: '5faeecf0-db6e-41a3-9448-afe1b096a6d2' }); // SegmentMismatch otherwise