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:
- Authenticate the user with your normal session.
- Check your product rules: conversation or call membership, tenant, role, blocks, subscription, appointment time.
- Derive
userId,deviceId,tenantIdand 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
| Caller | Credential | Can | Cannot |
|---|---|---|---|
| Your backend | Service key | Create calls/conversations, mint tokens, moderate, suspend users (per scope) | Use console endpoints |
| User’s device | Messaging token | Read and send in conversations it belongs to; presence in its tenant; typing; files | Add itself to conversations; act as other users |
| User’s device | Join token | Join one call with one role | Join 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), scopeusers:write): stops new tokens, disconnects their sockets and removes them from calls.unsuspendrestores 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.