Realtime Socket.IO API for live tenant events
Get live tenant events and shared-document locking over Socket.IO, with missed-event replay.
What it does
- The Realtime API pushes changes to your app the moment they happen, over Socket.IO. Connect once with the user's token and you are placed in a room for your tenant. Events for your tenant arrive as they are published, and nobody else's events reach you.
- It solves the polling problem. Instead of asking every few seconds "has anything changed?", your page listens. Dashboards update, lists refresh and toasts appear without a reload, and the server is not hit by a stream of empty requests.
- Connecting is simple. Open a Socket.IO connection to /socket.io and pass the JWT in the auth payload as token. Tokens in the URL query string are refused on purpose, because query strings end up in logs and browser history. If a session is revoked, the tenant is suspended or the user is deactivated, open sockets are cut by a periodic check.
- Missed something while offline? Add a since checkpoint (a stream id or an ISO-8601 time) as a query parameter on the connection, and the server replays tenant events you missed to that socket only. Events are kept on a Redis stream per tenant. Pass * to skip replay and go live only.
- There is also a collaboration layer for shared documents. Each document has a room per tenant. Clients can join and leave, ask for the edit lock, release it, broadcast a change and share presence such as a cursor. Only the lock holder can broadcast changes, waiting requests queue first-come first-served, and the lock expires on its own after five minutes. Change history is kept.
- How events get in: tenant events are published by Takelan platform services over an internal, service-authenticated route. Your own app consumes them and uses the document collaboration events. That route is not a customer publishing API, and it is not exposed to agents.
- We do not publish connection limits, latency or delivery-time numbers.
- Affordable by design. Start free* inside platform limits. *Free within platform limits; usage beyond limits may be charged to maintain the platform. Connected ShadowCradle organizations can switch on Takelan SSO and these free* services with one switch. Airgap licences work without any Takelan connection.
See how it works
Live tenant events, no polling
Shared documents with an edit lock
Example use cases
A live dashboard
An operations screen listens for tenant events and updates a status tile when something changes, with no refresh button.
Never miss an event after a reconnect
A laptop wakes from sleep and the socket reconnects with a since checkpoint. The server replays what was missed, so the list catches up.
Two people, one document
An editor asks for the lock. The second person sees who holds it and joins the queue. When the first releases it, the next in line gets the lock.
Show who is here
A shared document view broadcasts presence and cursor positions so teammates see each other.
Stay in step with a long job
A web app starts an import and listens for tenant events that report progress, instead of polling a status endpoint.
Safe by tenant
A multi-tenant SaaS needs to be sure that user A never receives user B's events. Rooms are chosen from the verified token, never from anything the browser sends.
Try it
Connect from a browser (JavaScript)
import { io } from 'socket.io-client'
const socket = io('https://www.takelan.com', {
path: '/socket.io',
auth: { token: accessToken }, // the user's SSO JWT, never in the URL
query: { since: lastSeenIso } // optional: replay tenant events after this point; '*' = live only
})
socket.on('tenant_event', (event) => {
console.log(event.event_type, event.resource_type, event.resource_id)
})
socket.on('tenant_event_replay_error', (e) => console.warn(e.message))
socket.on('connect_error', (err) => console.error(err.message))Access tokens are short-lived (the SSO access token lasts 1800 seconds), so reconnect with a fresh token after a refresh. Use your own origin if your deployment serves the realtime service elsewhere.
Ask for the edit lock on a shared document
socket.emit('JOIN_DOCUMENT', { documentId: 'doc-42' })
socket.emit('DOCUMENT_LOCK_REQUESTED', { documentId: 'doc-42' })
// when you hold the lock:
socket.emit('DOCUMENT_CHANGED', { documentId: 'doc-42', change: { op: 'insert', at: 12, text: 'Hello' } })
socket.emit('DOCUMENT_LOCK_RELEASED', { documentId: 'doc-42' })Payload field names are a sketch. Check the server events in your environment before you ship.
Endpoints
GET /socket.io/Socket.IO endpoint. Connect with auth.token. Optional since checkpoint for replay.POST /internal/publishPlatform services only: store and broadcast a tenant event (service token). Not for customer apps.
MCP
Not available as tools. Socket and internal publish routes are excluded from /mcp/utils on purpose. An agent that needs current state can read it from the REST APIs through /mcp/utils (read-only by default, writes off by default). About MCP
Common questions
how to get realtime updates in a web app without polling
Open a Socket.IO connection to /socket.io with the user's JWT in the auth payload, then listen for tenant_event. You get events for your tenant as they happen.
how do I authenticate a socket.io connection
Send the token in the auth object as token. Tokens in the query string are refused. Invalid or revoked sessions get a connect_error.
can I replay events I missed while offline
Yes. Pass a since query parameter on the connection, either a Redis stream id or an ISO-8601 time. Missed tenant events are replayed to that socket only. Use * to skip replay.
how does document locking work
A client requests the lock for a document. If someone holds it, the request waits in a first-in first-out queue. The holder can broadcast changes and release the lock. The lock expires after five minutes if it is not released.
can one tenant see another tenant's events
No. Rooms are chosen from the verified token on the server. Document rooms are also keyed by tenant, so the same document id in two tenants is two rooms.
can my own app publish events to the room
Not through this API today. Publishing is an internal route for Takelan platform services. Your app consumes tenant events and uses the document collaboration events. For app-to-person alerts, use the Notifications API.
what happens to my socket if my session is revoked
A periodic check compares open sockets with the session service. If the session was revoked, the user was deactivated or the tenant was suspended, the socket is disconnected.
is the realtime api free
It is affordable by design: start free* within platform limits. *Free within platform limits; usage beyond limits may be charged to maintain the platform.