The Six Elements

Six elements

The integration model is built from six distinct concepts. Understanding what each one is — and what it deliberately is not — is the foundation for everything else.

The key boundary: everything left of TinySync is the ecosystem's responsibility. TinySync never reads ecosystem user records, session tokens, or role assignments. It only sees device IDs and group memberships — both of which are managed for it by the Platform Service.

The identity model

TinySync's identity unit is the device. A device is not a machine — it is a logged-in session of a specific user on a specific machine. The same laptop has two different device identities if two different users log in on it.

Device token format

Device tokens are custom bearer tokens, not JWTs. Each token encodes its device ID and a random secret:

tsdev_{device_id}_{secret}

device_id  — opaque identifier, assigned at registration
secret     — 32 random bytes, base64url-encoded

The server stores only the SHA-256 hash of the secret (with a domain separator). The raw token never persists on the server side. This means a device token cannot be recovered after issuance — only revoked.

One token per session

There is exactly one device token per (user × physical device) pair. If Alice logs in on her MacBook, the Platform Service registers a device and issues one token. That token lives on Alice's MacBook. It is not shared with Bob's MacBook, even if both are in the same group.

Who knows about users?

TinySync does not. The Platform Service maintains the user_id → [device_ids] mapping. When an ecosystem event arrives (user added to workspace, user promoted to admin), the Platform Service translates it into device operations and calls the TinySync API.