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. **Most readers will not call this directly.** It's the wallet's plumbing. We document it for transparency and so wallet implementers have a precise reference. ## 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: | Header | Value | |---|---| | `X-Keon-Timestamp` | Unix timestamp in **seconds** as an ASCII integer. Must be within **5 minutes** (300 s) of server time. Out-of-window requests get `403 Request expired`. | | `X-Keon-Signature` | Lowercase hex HMAC-SHA256 digest. See the message construction below. | 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 ``` GET:: ``` Three ASCII fields, colon-separated, no trailing newline. `` is the path segment as the server sees it (lowercase hex, as you put it in the URL). `` is the exact string you put in `X-Keon-Timestamp`. ### `PUT` request message ``` PUT::: ``` `` 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 ```python import hashlib, hmac, time def sign_get(auth_key_hex: str, lookup_hash: str) -> tuple[str, str]: ts = str(int(time.time())) msg = f"GET:{lookup_hash}:{ts}".encode() sig = hmac.new(bytes.fromhex(auth_key_hex), msg, hashlib.sha256).hexdigest() return ts, sig def sign_put(auth_key_hex: str, lookup_hash: str, blob: str) -> tuple[str, str]: ts = str(int(time.time())) body_hash = hashlib.sha256(blob.encode()).hexdigest() msg = f"PUT:{lookup_hash}:{ts}:{body_hash}".encode() sig = hmac.new(bytes.fromhex(auth_key_hex), msg, hashlib.sha256).hexdigest() return ts, sig ``` ```javascript import { createHmac, createHash } from 'node:crypto'; function signGet(authKeyHex, lookupHash) { const ts = Math.floor(Date.now() / 1000).toString(); const msg = `GET:${lookupHash}:${ts}`; const sig = createHmac('sha256', Buffer.from(authKeyHex, 'hex')) .update(msg).digest('hex'); return { ts, sig }; } function signPut(authKeyHex, lookupHash, blob) { const ts = Math.floor(Date.now() / 1000).toString(); const bodyHash = createHash('sha256').update(blob).digest('hex'); const msg = `PUT:${lookupHash}:${ts}:${bodyHash}`; const sig = createHmac('sha256', Buffer.from(authKeyHex, 'hex')) .update(msg).digest('hex'); return { ts, sig }; } ``` 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. ```bash TS=$(date +%s) SIG=$(echo -n "GET:$LOOKUP_HASH:$TS" | openssl dgst -sha256 -hmac "$AUTH_KEY_BIN" -hex | awk '{print $2}') curl "https://api.tokenkithq.io/api/keon/sync/$LOOKUP_HASH/" \ -H "X-Keon-Timestamp: $TS" \ -H "X-Keon-Signature: $SIG" ``` ### Responses **200 OK** — blob exists and signature verified: ```json { "version": 7, "blob": "", "last_modified": "2026-05-23T11:42:18+00:00" } ``` **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: | Field | Required | Notes | |---|---|---| | `blob` | yes | The encrypted ciphertext as a string (typically base64). Server stores it verbatim. | | `version` | yes | Integer. Must be strictly greater than the server's currently-stored version. On first PUT, ≥ 1. | | `auth_key` | **only on first PUT for this `lookup_hash`** | Hex string. Becomes the HMAC key for all future requests on this hash. Omit on subsequent PUTs — the server uses its stored copy and ignores any value sent here. | ```json { "blob": "", "version": 8, "auth_key": "" } ``` ### Responses **200 OK** — write accepted: ```json { "version": 8, "status": "ok" } ``` **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`. ```json { "error": "Version conflict", "server_version": 8 } ``` **400 Bad Request** — missing `blob`, or first PUT (no stored row) without an `auth_key`. **403 Forbidden** — missing headers, expired timestamp, or signature mismatch. **Version-conflict semantics changed from what older client code may assume.** Equal versions also conflict (`<=`, not `<`). Always increment past the server's reported `server_version`, never just write back what you had. ## 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:::` 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.) **`lookup_hash` must be unguessable.** It's the only thing identifying a blob — anyone who knows it and the corresponding `auth_key` can read and overwrite the blob. Derive it from the master key with a fixed-purpose KDF; do not hand-roll. ## Status codes summary | Code | When | |---|---| | `200` | GET success / PUT accepted | | `400` | Missing `blob`; first PUT without `auth_key` | | `403` | Missing headers; expired timestamp (> 300 s skew); signature mismatch | | `404` | GET when no blob is stored for this `lookup_hash` (checked **before** signature verify, so a 404 here doesn't mean your signature was wrong) | | `409` | PUT with `version <= stored_version` | ## See also - [Keon Wallets Directory](./keon-wallets-directory) - the public-facing wallet registry

Documentation

Querying Tokens

Listed tokens

All tokens

Listed vs. all