Skip to Content
LYNKORIADocs

Core concepts

Projects, environments, tenants, users, devices, credentials and how a request flows through Lynkoria.

The trust model

Lynkoria never authenticates your end users. Your product does that, then vouches for them:

 Browser / app ──(your session)──▶ Your backend ──(service key)──▶ Lynkoria API
      │                                 │
      │◀──── short-lived user token ────┘
      │
      └──(user token)──▶ Lynkoria API, socket and media
  1. The user signs in to your product.
  2. Your backend checks what they may do (membership, roles, blocks, subscriptions), then calls Lynkoria with its service key to create a call or conversation, or to mint a user token.
  3. The app uses only that token. Tokens are short-lived and scoped to one user, device and environment, so leaking one exposes little.

Resources

ConceptWhat it is
OrganizationYour company account in the console. Console roles are granted per organization or per project.
ProjectOne product, such as vibelynk. Owns environments, keys, usage and audit history.
Environmentstaging or production inside a project. Holds allowed origins, enabled features, quotas, messaging policy and webhook settings. Data never crosses environments.
TenantAn optional partition inside an environment, such as a workspace or school. Messaging tokens and conversations carry a tenantId (default default); presence and conversations stay within it.
UserYour product’s user ID, 1–128 characters of A-Z a-z 0-9 . _ @ -. Lynkoria stores no profile.
DeviceOne app instance (a browser tab, a phone). Each device has its own token and presence lease, so one user can be online on several devices.
ConversationA durable message thread with members. Identified by a Lynkoria UUID; you can attach your own productConversationId.
CallA media room (one_to_one, group or livestream). Identified by a UUID; created idempotently from your productCallId.

Credentials

CredentialHeld byLifetimeUsed for
Service keyYour backend onlyUntil revokedEvery server-side API call. lynk_test_… or lynk_live_….
Messaging tokenThe user’s device10 minutesREST messaging, presence and the realtime socket.
Call join tokenThe user’s device5 minutes to joinConnecting to one call’s media room with one role.
Webhook secretYour backend onlyUntil rotatedVerifying webhook signatures. whsec_….

The client SDK refreshes messaging tokens automatically by calling your getMessagingToken function before they expire. See authentication.

Features are switched per environment

Each environment enables features independently: calls (on by default), livestream, messaging, presence, attachments and single-device calls. A request for a disabled feature fails with feature_disabled. Turn features on in the console’s Environments tab.

Ordering and delivery

  • Every change in a conversation (new message, edit, delete, reaction) gets the next sequence number (seq) for that conversation. The client SDK applies events in sequence order, drops duplicates and fetches any gap from history, including after a reconnect.
  • PostgreSQL is the source of truth. The socket is a fast path, so a message is never lost because a socket dropped.
  • Webhooks are delivered at least once; deduplicate by event id.

Environments and keys in practice

Use staging with lynk_test_ keys for development and testing, and production with lynk_live_ keys for real users. A Lynkoria deployment accepts only one key mode, so a test key can never reach production data.

On this page