3.2 KiB
Mesh Developer Quickstart
This is the shortest path for a new app to use Mesh without depending on a server-owned account secret.
1. Create an Account Key
Generate an ML-DSA-44 keypair on the client. The account ID is the lowercase hex SHA-256 hash of the public key bytes.
Keep the private key on the device. The relay receives the public key and signatures, not the private key.
2. Request a Challenge
curl "$MESH/api/v1/sync/challenge?user_id=$ACCOUNT_ID"
The response contains a single-use nonce. Sign the canonical message with the account private key:
daochi-sync-v1
POST
/api/v1/sync/login
<sha256 hex of exact login body bytes>
<challenge nonce hex>
3. Login
Post the signed login JSON to receive a bearer token and server time:
curl -X POST "$MESH/api/v1/sync/login" \
-H "Content-Type: application/json" \
-d @login.json
Bearer tokens are operational credentials. When one expires or receives 401,
repeat challenge and login as long as the local account key still exists.
4. Register an App Manifest
New apps should use signed manifests:
curl -X POST "$MESH/api/v1/apps/register-signed" \
-H "Content-Type: application/json" \
-d @manifest.json
The manifest declares:
- app ID and display metadata;
- active Ed25519 app keys;
- owned collection prefixes;
- capabilities and token policies;
- compatibility windows when needed.
5. Write One Encrypted Record
Use the encrypted record profile for the ciphertext envelope, then sync it:
{
"protocol_version": 6,
"app_id": "exampleapp",
"user_id_hash": "account-id",
"client_id": "example-client-1",
"encrypted_records": [
{
"collection": "private.exampleapp.v1.records",
"id": "note-1",
"key_id": "main-2026-09",
"nonce": "base64url-24-byte-nonce",
"ciphertext": "base64url-envelope-json"
}
]
}
Protocol v6 strict requests also include X-Mesh-Tx, signed by the account
key and an active app key.
6. Read It Back
Call sync again with the last seen server version. Mesh returns records newer than that version and does not need to parse the ciphertext.
curl --compressed -X POST "$MESH/api/v1/sync" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "X-Mesh-User: $ACCOUNT_ID" \
-H "X-Mesh-Since-Version: $SERVER_VERSION" \
-d @sync.json
--compressed negotiates a supported response encoding and decodes it for the
caller. Mesh prefers Zstandard when accepted and retains gzip and identity
for other clients. The node advertises http-zstd-v1 when it also accepts
compressed Zstandard request bodies. If compressing an upload, sign the exact
uncompressed JSON bytes first, then compress and set Content-Encoding.
See HTTP compression for bounds and transport behavior.
7. Inspect Trust and Sync State
Useful checks while developing:
GET /api/v1/apps/{app_id}for app manifest state;GET /api/v1/apps/{app_id}/collectionsfor collection ownership;GET /api/v1/sync/diagnosticsfor account sync state;GET /api/v1/nodefor node identity, protocol bounds, and public usage;GET /openapi.jsonfor the current API contract.