Data Sync

App services

Data Sync

On this page

Store app data in personal or organization spaces: multi-device sync, team sharing, version conflict detection and deduplicated attachments, with optional end-to-end encryption (the server only keeps ciphertext). CZL Connect does not parse your data; it stores, versions and distributes it. Conflict handling, encryption and the local database live in the client. Go clients integrate with the public SDK github.com/woodchen-ink/go-web-utils/syncsdk without implementing the protocol or any cryptography themselves.

Use cases

  • A desktop or mobile app without its own backend that needs multi-device sync or shared team data
  • Sensitive data (customer lists, prices) that neither the server nor operators should be able to read
  • A team plan together with Organizations: members share one space and their role decides whether they can write

Requirements

Available on the app owner's plan. The quota is the total sync storage (documents + revisions + attachments) across all apps of the account:

PlanTotal sync storage
LiteNot available
Plus20 GB
Pro200 GB
EnterpriseUnlimited

Over the quota, new spaces are refused while existing spaces keep accepting writes. After a downgrade to Lite, spaces become read-only (pull and attachment downloads still work); no data is deleted.

Enabling it for an app

Open the app → Data sync (only the app owner can change it):

SettingDescription
Enable data syncWhen off, the sync API refuses access. Stored data is kept and comes back once re-enabled
End-to-end encryptionoff: the server encrypts stored data with a per-space derived key. required: only client-encrypted envelopes are accepted and attachment IDs are not plaintext digests. Cannot be turned off once required
CollectionsRegister collection names (lowercase letters, digits, -, _, up to 50), the minimum write role (default member), append-only, and revisions to keep (0–20). Names must match the client code; writes to unregistered collections are refused, so renaming or unregistering one stops the client writing to it, while stored documents stay and can still be pulled
Max document size1 MB by default and at most; can be lowered
Storage / documents per space0 for unlimited (still bound by the account quota)
Append-only retention365 days by default and at most; can be lowered

The same page shows the number of spaces, documents and attachments, this app's storage (and how much of it is attachments), writes in the last 30 days, and the account total.

Concepts

  • Space: the personal space me (one per user per app) or an organization space (addressed by the organization's public ID). A user can access their own personal space and the spaces of organizations they belong to
  • Collection: a name registered by the app, such as shipments or contacts. Visible to the server, so do not put business data in it
  • Document: unique by (space, collection, document ID); payload is opaque JSON. Document IDs are 1–200 bytes without / \ ? # or control characters, and are visible to the server too
  • Sequence: a monotonically increasing counter per space. A document's rev is the sequence number of its last write, and the pull cursor is a sequence number as well
  • Author: each document's updatedBy (the user's identifier in this app, same as the OIDC sub) and updatedAt are set by the server from the token and delivered outside the ciphertext. Show "who changed it" from these two fields only

Roles and read-only

RoleSync permissions
Owner of a personal spaceTreated as owner
owner / adminRead and write; with end-to-end encryption, wrap the space key for new members and rotate it after removals
memberRead and write (subject to each collection's minimum write role)
viewerRead only

When an organization is read-only (for example its owner is banned) or the plan does not include sync, the space can only be pulled and its attachments downloaded; writes are refused as a whole with 403 40302 space_readonly.

When the app has billing and entitlements enabled, sync is gated by subscription: a personal space needs the user's own active subscription and an organization space needs the organization's. Without one (never bought, expired past the grace period, or refunded) the space is read-only and writes return 40302. With an active subscription the space storage limit comes from the plan quota quotas.syncStorageGB (GB, decimals allowed), falling back to the per-space quota in the app's sync settings. Apps without billing ignore subscriptions.

Authentication and rate limits

All endpoints live under https://connect.czl.net/api/sync/v1 and use the user's OAuth2 access token (Authorization: Bearer <access_token>, the same token you get from OAuth2). Spaces are resolved within the token's app only. An invalid token returns 401 40101; the SDK refreshes the token and retries once.

Rate limits are per (user, space): 600 requests per minute. Over the limit you get 429 42901 with Retry-After.

Response format

Success is HTTP 200 with {"code": 200, "data": ..., "msg": "success"}. Errors use the matching HTTP status, a business code and a snake_case English phrase; on 409, data carries the server's current document or record:

JSON
{"code": 40901, "data": {"collection": "shipments", "id": "s1", "rev": 12, "deleted": false, "payload": {...}, "updatedBy": "...", "updatedAt": "2026-11-20T08:00:00.123Z"}, "msg": "version_conflict"}
CodeHTTPMeaning
40001400Malformed request (invalid_body / invalid_op / invalid_batch / grant_for_non_member ...)
40002400Payload is not valid JSON, or an end-to-end encrypted app received something other than an envelope
40003400A space key rotation does not cover every enrolled member
40004400In a non-encrypted app, the attachment content does not match the blobId digest
40101401Invalid or expired token
40301403Not a member of the space (also returned when the organization does not exist)
40302403Space is read-only
40303403Data sync is not enabled for the app
40304403Account is banned
40310403Collection not registered (per operation)
40311403Role below the collection's minimum write role (per operation)
40312403Append-only collections cannot be updated or deleted (per operation)
40401404Document, attachment or device request not found; not_enrolled means end-to-end encryption is not set up yet
40901409Version conflict (baseRev differs from the current rev); data is the current document
40902409State conflict: public key already exists, recovery version mismatch, a newer space key version was created first, or the device request is in the wrong state
41001410The cursor is older than purged tombstones; do a full resync
41301413Document too large (payload_too_large), space quota (space_quota_exceeded), no account quota left for a new space (account_quota_exceeded), or an attachment over 32 MB
42901429Too many requests
50301503Sync is temporarily unavailable

A 403 / 413 inside a batch result affects only that operation. As the response to the whole request (read-only space, not a member, new space over quota), the client should keep its local changes and retry later.

Endpoints

Method and pathDescription
GET /spacesAccessible spaces: id, type, name (organization name), role, readonly, e2e, seq, quota, usage
GET /spaces/{space}/changes?since=&limit=Documents with rev > since (tombstones included) in ascending rev, limit up to 500; returns docs, cursor (the next since), hasMore and presence (other users and your other devices, see "Rules · Editing presence")
PUT /spaces/{space}/docs/{collection}/{id}Body {"baseRev": 0, "payload": {...}}, baseRev is 0 for a new document; returns the written metadata (without payload)
DELETE /spaces/{space}/docs/{collection}/{id}?baseRev=Writes a tombstone, same rules as PUT
POST /spaces/{space}/batch{"ops": [{"op": "put" | "delete", "collection", "id", "baseRev", "payload"}]}, up to 100 ops; returns results matching the request order (status, code, msg, doc); not atomic
GET /spaces/{space}/docs/{collection}/{id}/revisionsHistory of a document in a collection with revisions enabled, newest first
HEAD /spaces/{space}/blobs/{blobId}Whether an attachment exists (200 / 404), used to deduplicate before uploading
PUT /spaces/{space}/blobs/{blobId}Upload an attachment (raw bytes, up to 32 MB); idempotent, an existing attachment is never overwritten
GET /spaces/{space}/blobs/{blobId}302 to a presigned download URL valid for 5 minutes
PUT /spaces/{space}/blob-refsOptional reference reconciliation: {"blobIds": [...]} lists every attachment still referenced in the space (owner / admin); the rest are marked unreferenced and deleted after 30 days. Without it, attachments are never cleaned up
GET /spaces/{space}/eventsSSE: event: changed with {"seq": n} on new writes, event: presence with {"presence": [...]} when others start or stop editing; if Last-Event-ID is below the current sequence, one changed is sent right away; a comment heartbeat every 25 seconds
PUT /spaces/{space}/presence/{collection}/{id}"Editing" heartbeat, expires after 60 seconds
GET / PUT /keys/meYour public key and encrypted private key copy (end-to-end encryption)
GET /spaces/{space}/keysYour wrapped keys for each version in the space, members waiting for a key, all enrolled members, and whether rotation is required
PUT /spaces/{space}/keys/{version}Owner / admin submits wrapped keys: rotate: true creates a new version (must be current + 1 and cover every enrolled member), otherwise grants an existing version
POST /devices/requestsA new device opens an approval request (see "End-to-end encryption" below)
GET /devices/requestsAn existing device lists the caller's pending requests
GET / DELETE /devices/requests/{id}Read a request's status / reject or withdraw it
POST /devices/requests/{id}/{step}Advance the request; step is challenge / reveal / approve / claim

Rules

  • Write check order: token → space access (membership, read-only, entitlement) → collection registration and minimum write role → document size and format → quota → version
  • Version conflicts: when baseRev differs from the server's current rev, you get 409 with the current document, and the client decides whether to overwrite, keep the server version or save a copy. If a retry finds that the server content is exactly what it sent last time (the response was lost), the SDK treats it as a success
  • Tombstones and cursors: deletes write tombstones, which are purged after 180 days. changes with a cursor older than purged tombstones returns 410; the client clears its local copy and pulls again from 0
  • Append-only collections: new documents only (baseRev 0); updates and deletes return 403 40312. Suited to activity logs: entries are encrypted as usual, and the author and time come from the server's updatedBy / updatedAt, so members cannot impersonate others or erase entries. Entries older than the retention period are purged by the server
  • Revisions: when enabled for a collection, the previous version is saved before every overwrite or delete, keeping the latest N; revisions count toward storage. Lowering N trims the extra revisions on that document's next write; setting it to 0 stops new revisions but keeps existing ones. Restoring is up to the client: read revisions, take the old payload, and PUT it back as a normal write (it gets a new rev, and the current content goes into history)
  • Editing presence: tracked per device. Clients send X-Sync-Device on every request (a stable per-device ID, 1–64 letters, digits, - _ ., generated once and stored on the device, never synced with settings) and an optional X-Sync-Device-Name (display name, UTF-8 percent-encoded, up to 64 characters). Presence entries are {collection, id, userId, deviceId, deviceName, expiresAt}; changes and SSE exclude only the caller's own device, so the same account opening the same document on another device shows up too (in a personal space this is how you warn "in use on another device"). Older clients without X-Sync-Device are still filtered by account and never see their own devices; a malformed device ID is treated as absent
  • Non-encrypted apps: payloads are encrypted with AES-GCM under the space key before being stored and decrypted on read. Key order and whitespace may be normalized, so do not rely on byte-for-byte equality

Attachments

  • blobId is 64 lowercase hex characters: the plaintext SHA-256 for non-encrypted apps (checked by the server), or an HMAC-SHA256 for end-to-end encrypted apps (the attachment ID key is per space, so duplicates are detected within a space without revealing plaintext digests), with chunked ciphertext as content
  • Attachment references are written into document payloads by the app; the server does not parse them
  • Attachment sizes count toward space and account storage. Downloads redirect to object storage with a 302, and the Authorization header is not forwarded

End-to-end encryption

With required, the server only stores:

DataNotes
User public key (X25519) and encrypted private key copyPUT /keys/me: recoveryVersion is 1 the first time; resetting the recovery code keeps the public key and increments the version; a version mismatch or an existing public key returns 409 40902
Wrapped space keysWrapped with each member's public key, stored per (space, version, member)
Document envelopes{"v":1,"kv":<key version>,"nonce":"...","ct":"..."}; the server only validates the format
  • New members: after accepting an organization invite and enrolling, they appear in pending. Any owner / admin client wraps the key for them on its next sync; until then they can see the space but cannot read its content
  • Removed members: the server deletes their wrapped keys and sets rotationRequired; the next owner / admin client online rotates to a new version. Copies already on the removed member's devices cannot be revoked
  • New devices: unlock the private key copy with the recovery code, or have a signed-in device approve it: the new device sends POST /devices/requests (temporary public key + commitment) → the existing device sends challenge (nonce) → the new device sends reveal (nonce) → both show the same 6-digit code → the existing device sends approve (the private key sealed to the temporary key) → the new device sends claim. Requests expire after 10 minutes, each value can be written only once, and DELETE from either side rejects or withdraws the request. The user gets a security notification in the notification center when a device is approved or the recovery code is reset
  • Unrecoverable cases: if a user loses all devices and the recovery code, their personal space cannot be recovered. CZL Connect support cannot recover it either, so make sure users save their recovery code when enrolling

Go SDK

Go
import "github.com/woodchen-ink/go-web-utils/syncsdk"

client, _ := syncsdk.NewClient(syncsdk.ClientOptions{
	BaseURL: "https://connect.czl.net/api/sync/v1",
	Tokens:  tokens, // implements Token(ctx), optionally InvalidateToken (refresh on 401)
	// per-device ID (kept in the data dir, not synced) so presence is tracked per device; name is optional
	DeviceID:   deviceID, // syncsdk.LoadOrCreateDeviceID(filepath.Join(dataDir, "device-id"))
	DeviceName: "Office desktop",
})
keys, _ := syncsdk.NewKeyManager(client, keyStore, syncsdk.KeyManagerOptions{Namespace: "myapp/" + userID})
engine, _ := syncsdk.NewEngine(syncsdk.EngineOptions{
	Client: client, Keys: keys, // pass nil Keys when end-to-end encryption is off
	Outbox: outbox, Cursors: cursors, Applier: localDB, Resolver: resolver,
	AppendOnly:   []string{"activity"},
	BlobCacheDir: blobCacheDir,
})

_ = engine.Save(ctx, "me", "shipments", id, row.Rev, payload) // queued even when offline
go engine.Subscribe(ctx, "me", syncsdk.SubscribeOptions{})     // SSE with polling fallback

Your app implements a persistent outbox, a cursor store, a local key store (Windows DPAPI / macOS Keychain), an Applier that writes changes to the local database, and a conflict callback. See the SDK documentation for enrollment, recovery codes, device approval, member grants and rotation. For integration tests you can start with the SDK's in-process fake server syncsdk/synctest, which implements the same contract as this service.

Retention

DataKept for
DocumentsUntil deleted (tombstone) or the space is cleaned up
Tombstones180 days
Append-only collectionsApp setting, 365 days by default
RevisionsLatest N per document
Unreferenced attachments30 days after being marked by reference reconciliation
Read-only spacesA deletion notice is recorded after 90 days read-only; deletable 30 days later (enabled by CZL Connect administrators, off by default)
New device requests10 minutes
"Editing" presence60 seconds

Writes are not logged one by one; write counts and bytes are aggregated per (space, day). Space creation and cleanup are recorded in the app's operation log.