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- The user signs in to your product.
- 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.
- The app uses only that token. Tokens are short-lived and scoped to one user, device and environment, so leaking one exposes little.
Resources
| Concept | What it is |
|---|---|
| Organization | Your company account in the console. Console roles are granted per organization or per project. |
| Project | One product, such as vibelynk. Owns environments, keys, usage and audit history. |
| Environment | staging or production inside a project. Holds allowed origins, enabled features, quotas, messaging policy and webhook settings. Data never crosses environments. |
| Tenant | An 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. |
| User | Your product’s user ID, 1–128 characters of A-Z a-z 0-9 . _ @ -. Lynkoria stores no profile. |
| Device | One 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. |
| Conversation | A durable message thread with members. Identified by a Lynkoria UUID; you can attach your own productConversationId. |
| Call | A media room (one_to_one, group or livestream). Identified by a UUID; created idempotently from your productCallId. |
Credentials
| Credential | Held by | Lifetime | Used for |
|---|---|---|---|
| Service key | Your backend only | Until revoked | Every server-side API call. lynk_test_… or lynk_live_…. |
| Messaging token | The user’s device | 10 minutes | REST messaging, presence and the realtime socket. |
| Call join token | The user’s device | 5 minutes to join | Connecting to one call’s media room with one role. |
| Webhook secret | Your backend only | Until rotated | Verifying 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.