Encrypted Sync (Keon)

The endpoint Keon Wallet uses to sync state between a user's devices. The blob is encrypted client-side before it leaves the device — the server stores opaque ciphertext and never sees plaintext.

Authentication

The endpoint does not use the api-key header — authentication_classes and permission_classes are explicitly empty on SyncView. Authentication is purely HMAC-SHA256, keyed with a per-user auth_key that the client generates locally during wallet creation. The API key is irrelevant here; sending one is harmless but ignored.

Two headers are required on every request:

Missing either header → 403 Missing signature or timestamp. Bad signature → 403 Invalid signature.

Signing — the exact message bytes

The HMAC message is method-aware. Get it wrong and every request fails verification.

GET request message

1GET:<lookup_hash>:<timestamp>

Three ASCII fields, colon-separated, no trailing newline. <lookup_hash> is the path segment as the server sees it (lowercase hex, as you put it in the URL). <timestamp> is the exact string you put in X-Keon-Timestamp.

PUT request message

1PUT:<lookup_hash>:<timestamp>:<sha256(blob_string)>

<sha256(blob_string)> is the lowercase hex SHA-256 of the blob field's string value — not the whole JSON body, not the body bytes. If the blob is base64 ciphertext like "Zm9v...", you hash that string verbatim (the bytes of those ASCII characters), without the surrounding JSON quotes.

Key used for HMAC

• First PUT for a lookup_hash (registration): the key is the auth_key value sent in the request body. The server stores it as auth_key_hash for subsequent verifications.
• Every request after that (GET, or subsequent PUT): the key is whatever the server has stored as auth_key_hash for that lookup_hash. The client must hold the same value locally.

Note that auth_key_hash is the literal auth_key value — it's a name from the model field, not an additional hash step. Both sides HMAC with the same hex string.

Reference signing code

The auth_key must be a hex-encoded byte string (any length the client picks — 32 bytes / 64 hex chars is a sensible default). The server treats it as opaque hex and feeds it to bytes.fromhex(...) before HMAC.

Retrieve the encrypted blob

GET /api/keon/sync/{lookup_hash}/

lookup_hash is a deterministic, opaque identifier the client derives from the user's master key (no user identity leaks). Hex string in the URL path.

1TS=$(date +%s)
2SIG=$(echo -n "GET:$LOOKUP_HASH:$TS" | openssl dgst -sha256 -hmac "$AUTH_KEY_BIN" -hex | awk '{print $2}')
3 
4curl "https://api.tokenkithq.io/api/keon/sync/$LOOKUP_HASH/" \
5  -H "X-Keon-Timestamp: $TS" \
6  -H "X-Keon-Signature: $SIG"

Responses

200 OK — blob exists and signature verified:

1{
2  "version": 7,
3  "blob": "<base64 ciphertext>",
4  "last_modified": "2026-05-23T11:42:18+00:00"
5}

404 Not Found — no blob stored for this lookup_hash yet. Treat as "fresh device, no prior sync".

403 Forbidden — one of: missing headers, expired timestamp, no blob exists for that hash (so server cannot verify), or signature mismatch. Body carries an error string identifying which.

Store or update the blob

PUT /api/keon/sync/{lookup_hash}/

Request body:

1{
2  "blob": "<base64 ciphertext>",
3  "version": 8,
4  "auth_key": "<hex, first PUT only>"
5}

Responses

200 OK — write accepted:

1{
2  "version": 8,
3  "status": "ok"
4}

409 Conflict — version is not newer than what's stored. The doc-stated rule is exact: server rejects when request.version <= stored_version. Re-fetch with GET, merge locally, and retry with stored_version + 1.

1{
2  "error": "Version conflict",
3  "server_version": 8
4}

400 Bad Request — missing blob, or first PUT (no stored row) without an auth_key.

403 Forbidden — missing headers, expired timestamp, or signature mismatch.

Registration walkthrough

For a brand-new wallet on a brand-new lookup_hash:

1. Client generates a random auth_key (e.g. 32 random bytes, hex-encoded).
2. Client derives lookup_hash from the user's master key.
3. Client encrypts its state → blob.
4. Client computes sha256(blob), then signs the PUT message PUT:<lookup_hash>:<ts>:<body_hash> using the newly-generated auth_key.
5. PUTs {blob, version: 1, auth_key} with X-Keon-Timestamp and X-Keon-Signature headers.
6. Server stores all three; returns {version: 1, status: "ok"}.

On every subsequent device that needs the same blob:

1. Client derives the same auth_key and lookup_hash from the master key (both deterministic from the same secret).
2. GET with HMAC signed by auth_key.

If the client cannot regenerate auth_key deterministically from the master key, the user can't sync across devices — the auth_key needs to be reproducible, not random, for multi-device wallets. (Pick the right KDF for your use case.)

Status codes summary

See also

• Keon Wallets Directory - the public-facing wallet registry