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:
| Plan | Total sync storage |
|---|---|
| Lite | Not available |
| Plus | 20 GB |
| Pro | 200 GB |
| Enterprise | Unlimited |
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):
| Setting | Description |
|---|---|
| Enable data sync | When off, the sync API refuses access. Stored data is kept and comes back once re-enabled |
| End-to-end encryption | off: 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 |
| Collections | Register 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 size | 1 MB by default and at most; can be lowered |
| Storage / documents per space | 0 for unlimited (still bound by the account quota) |
| Append-only retention | 365 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
shipmentsorcontacts. Visible to the server, so do not put business data in it - Document: unique by (space, collection, document ID);
payloadis 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
revis 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 OIDCsub) andupdatedAtare 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
| Role | Sync permissions |
|---|---|
| Owner of a personal space | Treated as owner |
owner / admin | Read and write; with end-to-end encryption, wrap the space key for new members and rotate it after removals |
member | Read and write (subject to each collection's minimum write role) |
viewer | Read 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:
{"code": 40901, "data": {"collection": "shipments", "id": "s1", "rev": 12, "deleted": false, "payload": {...}, "updatedBy": "...", "updatedAt": "2026-11-20T08:00:00.123Z"}, "msg": "version_conflict"}| Code | HTTP | Meaning |
|---|---|---|
40001 | 400 | Malformed request (invalid_body / invalid_op / invalid_batch / grant_for_non_member ...) |
40002 | 400 | Payload is not valid JSON, or an end-to-end encrypted app received something other than an envelope |
40003 | 400 | A space key rotation does not cover every enrolled member |
40004 | 400 | In a non-encrypted app, the attachment content does not match the blobId digest |
40101 | 401 | Invalid or expired token |
40301 | 403 | Not a member of the space (also returned when the organization does not exist) |
40302 | 403 | Space is read-only |
40303 | 403 | Data sync is not enabled for the app |
40304 | 403 | Account is banned |
40310 | 403 | Collection not registered (per operation) |
40311 | 403 | Role below the collection's minimum write role (per operation) |
40312 | 403 | Append-only collections cannot be updated or deleted (per operation) |
40401 | 404 | Document, attachment or device request not found; not_enrolled means end-to-end encryption is not set up yet |
40901 | 409 | Version conflict (baseRev differs from the current rev); data is the current document |
40902 | 409 | State 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 |
41001 | 410 | The cursor is older than purged tombstones; do a full resync |
41301 | 413 | Document 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 |
42901 | 429 | Too many requests |
50301 | 503 | Sync 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 path | Description |
|---|---|
GET /spaces | Accessible 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}/revisions | History 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-refs | Optional 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}/events | SSE: 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/me | Your public key and encrypted private key copy (end-to-end encryption) |
GET /spaces/{space}/keys | Your 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/requests | A new device opens an approval request (see "End-to-end encryption" below) |
GET /devices/requests | An 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
baseRevdiffers from the server's currentrev, you get409with 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.
changeswith a cursor older than purged tombstones returns410; the client clears its local copy and pulls again from 0 - Append-only collections: new documents only (
baseRev0); updates and deletes return403 40312. Suited to activity logs: entries are encrypted as usual, and the author and time come from the server'supdatedBy/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 oldpayload, andPUTit back as a normal write (it gets a newrev, and the current content goes into history) - Editing presence: tracked per device. Clients send
X-Sync-Deviceon every request (a stable per-device ID, 1–64 letters, digits,-_., generated once and stored on the device, never synced with settings) and an optionalX-Sync-Device-Name(display name, UTF-8 percent-encoded, up to 64 characters). Presence entries are{collection, id, userId, deviceId, deviceName, expiresAt};changesand 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 withoutX-Sync-Deviceare 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
blobIdis 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
Authorizationheader is not forwarded
End-to-end encryption
With required, the server only stores:
| Data | Notes |
|---|---|
| User public key (X25519) and encrypted private key copy | PUT /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 keys | Wrapped 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 sendschallenge(nonce) → the new device sendsreveal(nonce) → both show the same 6-digit code → the existing device sendsapprove(the private key sealed to the temporary key) → the new device sendsclaim. Requests expire after 10 minutes, each value can be written only once, andDELETEfrom 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
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 fallbackYour 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
| Data | Kept for |
|---|---|
| Documents | Until deleted (tombstone) or the space is cleaned up |
| Tombstones | 180 days |
| Append-only collections | App setting, 365 days by default |
| Revisions | Latest N per document |
| Unreferenced attachments | 30 days after being marked by reference reconciliation |
| Read-only spaces | A deletion notice is recorded after 90 days read-only; deletable 30 days later (enabled by CZL Connect administrators, off by default) |
| New device requests | 10 minutes |
| "Editing" presence | 60 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.