Skip to Content
LYNKORIADocs

Authentication

How your backend vouches for users, how tokens are issued and refreshed, and what you must authorize.

Your backend authorizes, Lynkoria enforces

Before asking Lynkoria for anything on a user’s behalf, your backend must:

  1. Authenticate the user with your normal session.
  2. Check your product rules: conversation or call membership, tenant, role, blocks, subscription, appointment time.
  3. Derive userId, deviceId, tenantId and call role on the server. Never copy them straight from the request body.

A service key is trusted across its entire environment, including every tenant. Tenant IDs constrain user tokens; they do not make a service key tenant-scoped.

Messaging tokens

const session = await lynkoria.sessions.messagingToken({
  userId: user.id,
  deviceId, // stable per app install or browser tab
  tenantId: workspace.id, // optional, defaults to "default"
});
// → { token: string, expiresAt: string }  (valid for 10 minutes)

Return the result only to that user. On the client, pass a function that fetches it:

import { createLynkoria } from '@lynkoria/client';

const client = createLynkoria({
  baseUrl: 'https://api.lynkoria.com',
  getMessagingToken: async () => {
    const res = await fetch('/api/lynkoria/session', {
      method: 'POST',
      credentials: 'same-origin',
    });
    if (!res.ok) throw new Error('Not signed in');
    return res.json(); // { token, expiresAt } or just the token string
  },
});

The SDK caches the token, refreshes it within 60 seconds of expiry, retries once on 401, refreshes the live socket session before it expires, and reconnects with backoff. Protect your token endpoint with session authentication and your usual CSRF defence.

When the signed-in user or tenant changes, create a new client. Never reuse a client, its cached token or its history across users.

Call join tokens

const credentials = await lynkoria.calls.joinToken({
  callId: call.id,
  userId: user.id,
  deviceId,
  displayName: user.name,
  role: 'participant', // livestreams also accept 'host', 'speaker' and 'viewer'
});
// → { url, token, identity, expiresAt }  (join within 5 minutes)

The media permissions come from the role, never from the client. The identity has the form project:user:device; use it for moderation.

What each credential can do

CallerCredentialCanCannot
Your backendService keyCreate calls/conversations, mint tokens, moderate, suspend users (per scope)Use console endpoints
User’s deviceMessaging tokenRead and send in conversations it belongs to; presence in its tenant; typing; filesAdd itself to conversations; act as other users
User’s deviceJoin tokenJoin one call with one roleJoin other calls; raise its own role

Requests for another project’s or tenant’s resources return not_found, so IDs cannot be probed.

Revocation and suspension

  • Revoke a service key: its next request fails immediately.
  • Disable an environment or project: new API requests and messaging activity are blocked. Connected media is not disconnected; end active calls separately.
  • Suspend a user (lynkoria.users.suspend(userId), scope users:write): stops new tokens, disconnects their sockets and removes them from calls. unsuspend restores access.

Presence and tenant boundaries

Anyone in the same environment and tenant can subscribe to a user’s presence. Lynkoria has no friend list or block list. If your product needs a narrower audience, use tenants to partition users or keep presence off.

On this page