Integrate · Chapter 4 of 5

The Platform Service

The ecosystem-owned translation layer: identity events in, device operations out.

The translation layer

The Platform Service is the translation layer between the external ecosystem and TinySync. It is not part of TinySync — it is a service that the ecosystem operator builds and runs, which speaks to TinySync's management API.

What the Platform Service owns

The user → devices mapping (which devices belong to which user)
The device registration lifecycle (when to create a device, when to revoke it)
The group management logic (when to add a device to a group, when to remove it)
Translation from ecosystem events to TinySync API calls

What the Platform Service does not own

It does not decide whether a sync succeeds or fails — that's TinySync's job
It does not manage file contents or metadata — that's the vault
It does not run on the client device — it's a server-side service

Platform service event flow

sequenceDiagram participant Eco as Ecosystem participant PS as Platform Service participant TS as TinySync API Eco->>PS: user.joined_workspace(user_id, workspace_id) PS->>PS: lookup user's devices PS->>TS: PUT /v1/groups/{group_id}/devices/{device_id} TS-->>PS: 200 OK Eco->>PS: workspace.vault_added(workspace_id, vault_id) PS->>PS: lookup workspace group PS->>TS: PUT /v1/groups/{group_id}/vaults/{vault_id} TS-->>PS: 200 OK Eco->>PS: user.left_workspace(user_id, workspace_id) PS->>PS: lookup user's devices, workspace group PS->>TS: DELETE /v1/groups/{group_id}/devices/{device_id} TS-->>PS: 200 OK

Platform Service is ecosystem-specific

Each ecosystem that embeds Drive builds its own Platform Service. The service shape is consistent (it talks to TinySync's management API), but the event sources and business logic are ecosystem-specific. A Scribe integration listens to Scribe events; a different product integration listens to its own events.

Design advantage

TinySync's sync engine is never modified per-ecosystem. All ecosystem-specific logic is pushed into the Platform Service. This means TinySync can serve multiple ecosystems simultaneously without any per-tenant code.

Try it live

The playground ↗ is a minimal Platform Service you can poke at: it keeps its own user catalog, translates users into TinySync devices, groups, and grants, and logs every management API call it makes — tokens redacted.

Token management

Token management is the operational concern of keeping device tokens secure and current across the fleet of devices an ecosystem manages.

Token storage on the client

In v1 the CLI and daemon store the device token in identity.json under the TinySync state directory, with owner-only (0600) file permissions. Moving the packaged desktop app's copy into the OS credential store (Keychain on macOS, Windows Credential Manager) is tracked follow-up work. The token is the device's long-lived credential — losing it (or having it revoked) requires re-registration.

Token storage on the server

TinySync stores only the SHA-256 hash of the secret portion of each token, with a domain separator to prevent cross-purpose hash reuse. The raw token is never stored. Validation is: hash the presented secret, compare to stored hash.

stored_hash = SHA-256("tinysync-device-token:" + secret_bytes)

No token rotation in v1

Device tokens do not expire and are not rotated automatically. Revocation is the only way to invalidate a token. This keeps the implementation simple and avoids the complexity of refresh flows on a sync engine that must work offline.

Future consideration

Token rotation (issuing a new token periodically while the old one is still valid for a grace period) is a reasonable v2 addition for high-security deployments. It is out of scope for v1.

Group token? No.

There is no "group token" — a single credential that grants access to all vaults a group can reach. Each device has its own token. The group structure is a server-side authorization record, not a credential. This ensures that compromising one device never grants access to the group's vaults from a different device — the attacker also needs the group membership to be in place, which is managed server-side.