FerryKey

API reference and test vectors

Every endpoint of api.ferrykey.com, and values to check your implementation against.

Protocol version 2 · Published 17 October 2026 · Part of the FerryKey protocol, which explains keys, encryption, signatures and the checks a client must make.

Contents

Conventions

Objects used below

Head (version 2)
{"Version":2,"AccountID":"…","Collection":"bookmarks","Seq":1,
 "EntryHash":[32 numbers],"Prev":[32 numbers],
 "LogSeq":2,"LogHash":[32 numbers],"Epoch":1,
 "DeviceID":"…","Time":1790000000,"Sig":"base64"}

SnapshotStatement
{"AccountID":"…","Collection":"bookmarks","Seq":1,"HeadHash":[32],"BlobHash":[32],
 "LogSeq":2,"LogHash":[32],"Epoch":1,"DeviceID":"… or root","Time":1790000000,"Sig":"base64"}

Entry (membership log)
{"AccountID":"…","Seq":2,"Prev":[32],"Time":1790000000,"Signer":"root","Op":2,
 "RootPub":null,"RecoveryKEM":null,
 "Device":{"SignPub":"base64","KEMPub":"base64","Collections":["bookmarks","meta"],"Proof":"base64"},
 "DeviceID":"","Epoch":1,"Collections":null,
 "Wraps":[{"Recipient":"device ID or recovery","Collection":"bookmarks","Ct":"base64"}],
 "Sig":"base64"}

The signed bytes for each object are defined in Signatures and Membership log. The JSON is only transport: signatures never cover it.

Errors

Errors are an HTTP status with a body {"Error":"message for people","Code":"stable code"}. Act on Code, not on the message. Any call can get busy or internal. An unknown path gets a plain-text 404, and a wrong method a 405.

StatusCodeMeaning and what to do
400bad_requestMalformed request. Don’t retry unchanged.
400invalid_entryA log entry broke a membership rule. The message says which.
400powSignup proof of work too weak.
400invalid_head, invalid_statementBad head or snapshot statement signature, scope or chain.
401unauthorizedMissing or bad signature headers, unknown device, bad signature, or a reused nonce.
401clock_skewThe device clock is more than 5 minutes off.
403device_removedThis device was locked out. Stop syncing and tell the user.
403forbiddenThe device may not use this collection.
403too_many_devicesThe account already has 20 devices.
404no_accountNo such account (never created, or deleted after 12 months unused).
404no_pushLive updates aren’t available.
409conflictSomeone else wrote first. Pull, merge, re-sign and retry.
409existsThe account already exists.
409log_changedThe membership log moved on. Read it again and retry.
409rotation_requiredA commit while a rotation is pending, or a write that isn’t in the current epoch. Rotate if you can, otherwise wait.
409snapshot_requiredUpload a signed snapshot at the current head, then commit again. Sent for the first write in a new epoch (the snapshot must be in the new epoch), and for a collection whose history still starts with retired protocol 1 heads and has no signed snapshot yet.
409upgrade_requiredProtocol version no longer supported (also sent for a commit whose head isn’t version 2, or a snapshot without a statement). Stop and update.
413too_big, request_too_bigBlob or body over the limit.
429rate_limitedToo many new accounts from this network today.
500internalServer fault. Back off and retry.
503busy, read_onlyOverloaded, or writes paused for maintenance. Back off and retry.

Limits and retention

LimitValue
Request body: /v1/log, /v1/pull, /v1/push-token64 KiB
Request body: /v1/account, /v1/log/append1 MiB
Request body: /v1/commit, /v1/snapshot8 MiB
Envelope blob (commit or snapshot), all collections5 MiB (5,242,880 bytes)
Devices per account20
Collections per account16
Signup proof of work22 bits
New accounts per network (IPv4 /24 or IPv6 /64) per UTC day5
Request clock skew±5 minutes
Pull responseup to 200 commits, about 8 MiB of blobs, 2,000 skipped heads
Commits and snapshots superseded by a newer snapshotdeleted within about 7 days (their signed heads are kept)
Accounts with no signed request from any devicedeleted after 12 months
Live-update token30 minutes

POST /v1/account

Creates an account. Unsigned: the entries sign themselves.

{"Init": Entry, "First": Entry, "PoW": 4903928}

The server replays both entries with the full membership rules, checks the proof of work, counts the signup against the network’s daily limit, then stores them.

Response: {}. Errors: bad_request, invalid_entry, pow, rate_limited, exists, read_only, request_too_big.

Server sees: the account ID, root public key, recovery public key, the collection names, the first device’s public keys and collections, wrapped keys it can’t open, entry times, and the network address (kept only as a keyed hash of the network and day).

POST /v1/log/append

Appends one membership entry (Add, Remove, Epoch or RotateRoot). Unsigned: the entry’s own signature is checked against the log.

{"Entry": Entry}

The entry’s Seq must be the log length + 1, and it must pass the membership rules against the current log. An Add is refused when the account already has 20 devices. On success the server sends a live update on collection log.

Response: {}. Errors: bad_request (missing entry, or an Init), no_account, conflict (wrong seq: read the log and rebuild), too_many_devices, invalid_entry, read_only, request_too_big.

Server sees: the entry: which device was added or removed, its public keys and collections, epoch changes, wrapped keys it can’t open, and who signed.

POST /v1/log

Returns the whole membership log. Signed by a member device or by root. Body: {}.

{"Entries":[Entry, …],
 "Seen":{"<device ID>":"2026-10-17T03Z", …}}

Seen is when each device last made a signed request, to the hour, in UTC. It isn’t signed and is for display only; it may be missing. Verify Entries as in What a client must check.

Server sees: which device asked, and when. It records each device’s last request time to the hour.

POST /v1/commit

Adds the next commit to a collection. Signed by a member device allowed the collection (not root).

{"Collection":"bookmarks","Epoch":1,"Blob":"base64 envelope","Head": Head}

The blob is sealed at (account, collection, kind 1, Head.Seq, Epoch). The server checks, in order:

  1. The device may use the collection (forbidden) and the blob is at most 5 MiB (too_big).
  2. No rotation is pending and Epoch is the current epoch (rotation_required). The blob’s header epoch equals Epoch (bad_request).
  3. Head.Version is 2 (upgrade_required).
  4. Head.Collection matches, Head.Seq is the current head + 1 and Head.EntryHash is SHA-256 of the blob (conflict).
  5. Head.LogSeq and Head.LogHash name the current log and Head.Epoch the current epoch (log_changed).
  6. If the previous commit is in an older epoch, the latest snapshot must be in the current epoch at the current head (snapshot_required).
  7. If the collection’s history starts with protocol 1 heads and it has no signed snapshot, a signed snapshot is needed first (snapshot_required).
  8. The head is signed by the calling device and links to the previous head (invalid_head).

Response: {"Seq": 43}. The server then sends a live update for the collection.

Errors: bad_request (malformed, signed by root, or blob epoch mismatch), forbidden, too_big (blob over 5 MiB or body over 8 MiB), rotation_required, upgrade_required, conflict, log_changed, snapshot_required, invalid_head, read_only, plus the errors any signed call can get.

Server sees: the collection name, commit number, epoch, the blob’s padded size, the head (device ID, log point, device time) and when it arrived. Not the content.

POST /v1/snapshot

Stores the whole content of a collection at its current head. Signed by a member device allowed the collection, or by root (used during a rotation). Used for the snapshot after every 32 commits, for a lock-out’s seal, and for a rotation’s snapshot in the new epoch.

{"Collection":"bookmarks","Seq":42,"Blob":"base64 envelope","Statement": SnapshotStatement}

The blob is sealed at (account, collection, kind 2, Seq, current epoch). Checks:

  1. Valid collection name the signer may use (bad_request, forbidden); blob at most 5 MiB (too_big).
  2. The blob’s header epoch is the current epoch (rotation_required). A snapshot is taken while a rotation is pending: that is a lock-out’s seal, still in the old epoch (see Lock out a device).
  3. Seq is the current head (conflict). It is 0 for a collection with no commits.
  4. A statement is present (upgrade_required). Its collection, seq and BlobHash match (bad_request). Its log point and epoch are current (log_changed). HeadHash is the hash of the head at Seq, or zero when Seq is 0 (conflict). It is signed by the caller, with DeviceID set to the caller’s device ID or root (invalid_statement).

Response: {}. Older commits and snapshots of the collection are deleted within about 7 days.

Errors: bad_request (malformed, bad collection name, or statement doesn’t match), forbidden, too_big (blob over 5 MiB or body over 8 MiB), rotation_required, conflict, upgrade_required, log_changed, invalid_statement, read_only, plus the errors any signed call can get.

Server sees: the collection name, seq, epoch, padded size, the statement (signer, log point, time) and when it arrived.

POST /v1/pull

Fetches what a device is missing. Signed by a member device allowed the collection, or by root.

request  {"Collection":"bookmarks","Since":40,"HeadsFrom":40}
response {"HeadSeq":45,
          "Heads":[Head, …] or null,
          "Snapshot":{"Seq":44,"Epoch":2,"Blob":"base64","Statement": SnapshotStatement} or null,
          "Commits":[{"Seq":44,"Head": Head,"Blob":"base64"}, …] or null,
          "More":false}

How the server answers:

  1. If the latest snapshot is above Since, the server first sends the heads from max(HeadsFrom, Since) + 1 up to the snapshot’s seq − 1 in Heads, 2,000 at most. If they don’t all fit, the response has only Heads and More: true; ask again with a higher HeadsFrom.
  2. Once the heads reach it, Snapshot is set and Commits starts at the snapshot’s seq. That first commit is there for its head (the snapshot’s anchor); don’t apply its change on top of the snapshot. A snapshot at seq 0 has no anchor, and commits start at 1.
  3. Otherwise Commits starts at Since + 1.
  4. Commits holds up to 200 commits and stops after about 8 MiB of blobs (always at least one). More is true when there are more: pull again with the new Since.

Reject a snapshot whose Statement is missing, and any head whose Version isn’t 2. Verify everything as in What a client must check.

Errors: bad_request (malformed or bad collection name), forbidden, plus the errors any signed call can get.

Server sees: which collection, which commit numbers the device has, and when it asked.

POST /v1/push-token

Returns a live-update token. Signed by a member device (not root). Body: {}.

{"URL":"wss://mqtt.ferrykey.com/","Token":"…","Filter":"fk/<topic>/+","Expires":1790001800}

Use it as in Live updates. Errors: bad_request (signed by root), no_push.

Server sees: which device asked, and when. The broker then sees the connection’s network address and how long it stays connected.

GET /health

For monitoring. 200 when the service and its storage are working, 503 when not. GET /health/live only says the process is up. Clients don’t need either.

Test vectors

All inputs here are test values (the all-zero secret, counting bytes, an all-zero device seed). They belong to no real user. Hex is lower case. Our test suite pins the final values (derived keys and account ID, the envelope blob hash, the signatures and head hash). The intermediate values were computed with the same code.

Recovery words

Key derivation (zero secret: “abandon … art”)

AMK                 0474de483dc0f2c22e15b5d9f743e24bd66dd1660b5248faf77f678e47bd67fc
root signing seed   98e23239e46c8bd6c508df5a967c78b47ed7344f7ad5352c0bcaad58300b6068
root public key     9c5ea86d8428702267ce52c2152925daf900eea12f09195a499b2a44f9288428
account ID          nh7arpf6fhmoco3xs3qwbqrk7zztadib
recovery key seed   4e047860ca6acb78b7c86e80ee6b6cc8a4698cb38856fa9539b1904f7bc156ce
                    48b27e7677832957201cc069333c2ae16c3bfc289c45d786acbd70c9f61f32dd
recovery public key 1216 bytes, starting 4d6a9ea470a7214115428909a7eb7514
  SHA-256           b3cfa9d91b3c8874696e7e259eb4a9017658a83ff96d6b3323c34e5d6e509c63
reserved "bookmarks" collection key (unused for data)
                    cb0c926e83604bb32b58c2a005ce497920a2bea25f97e9436d19bd7e981e9a0c

Envelope

key        000102…1f (bytes 0x00 to 0x1f)
salt       202122…3f (bytes 0x20 to 0x3f)
location   account nh7arpf6fhmoco3xs3qwbqrk7zztadib, collection "bookmarks",
           kind 1 (change), seq 7, epoch 3
plaintext  "hello ferrykey" (14 bytes)

message key  e82dec6d604044b4fd6a7f99a7bcecc468aa4a1aa57ef60d8e4b1813a5660ad7
nonce        117d24f8a97abc48a528c452
header       464b450101 00000003 202122…3f
AAD (123 bytes)
  66657272796b657920763120656e76656c6f706520616164
  464b45010100000003202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f
  000000206e6837617270663666686d6f636f3378733371776271726b377a7a7461646962
  00000009626f6f6b6d61726b73 01 0000000000000007
padded plaintext  0000000e 68656c6c6f206665727279 6b6579, then zeros to 1024 bytes
blob       1081 bytes = 41 header + 1024 + 16 tag
  ciphertext starts  0aed1d1831822c924b8a16d5…   (byte 41 onwards)
  tag                9a3a3ad3805eed63511cdcfb22e78f81
  SHA-256 of blob    d2e58b12b2f538b9c68af8a0b71595fef008a7f3f7e79857fbe604af4718a427

Signatures

One device signs a head, a snapshot statement and a request. In the inputs, 01… means the byte 01 followed by 31 zero bytes (likewise 02…, 03…).

device seed     32 zero bytes
device public   3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29
device ID       copdsqhgjnkjc4rardm2bv2bmkh4qjxa
account ID      nh7arpf6fhmoco3xs3qwbqrk7zztadib (the zero secret's account)
Head: version 2, collection "bookmarks", seq 1, entryHash 01…, prev zero,
      logSeq 2, logHash 02…, epoch 1, time 1
message
  0000001066657272796b65792076322068656164
  000000206e6837617270663666686d6f636f3378733371776271726b377a7a7461646962
  00000009626f6f6b6d61726b73
  0000000000000001
  0100000000000000000000000000000000000000000000000000000000000000
  0000000000000000000000000000000000000000000000000000000000000000
  0000000000000002
  0200000000000000000000000000000000000000000000000000000000000000
  00000001
  00000020636f7064737168676a6e6b6a6334726172646d32627632626d6b6834716a7861
  0000000000000001
signature
  c807895610706b917803b074e81b73c64524a4ae2c0cd7abcc1c9f29257c9608
  a1842ca6ee0b9487c67a8c94276105ae098aec8a7c9e694ce6279b04e3b51104
head hash = SHA-256(message | 00000040 | signature)
  aa9c54e64f4e07c7f8801d4e63c15bb5b6265cc4a041eebdf812db9098c5bd3c
Snapshot statement: collection "bookmarks", seq 1, headHash = the head hash above,
      blobHash 03…, logSeq 2, logHash 02…, epoch 1, signer = the device ID, time 1
message
  0000001466657272796b657920763220736e617073686f74
  000000206e6837617270663666686d6f636f3378733371776271726b377a7a7461646962
  00000009626f6f6b6d61726b73
  0000000000000001
  aa9c54e64f4e07c7f8801d4e63c15bb5b6265cc4a041eebdf812db9098c5bd3c
  0300000000000000000000000000000000000000000000000000000000000000
  0000000000000002
  0200000000000000000000000000000000000000000000000000000000000000
  00000001
  00000020636f7064737168676a6e6b6a6334726172646d32627632626d6b6834716a7861
  0000000000000001
signature
  6db30356b56166ceee9772b79a5e5b9e0aa9d2154f4df6495f75091cd96eca77
  b9fcf8017cd80edb6dcd17aa4c3576ffda60c62593cd9ddee75479e32312ac0e
Request: method "POST", host "api.ferrykey.com", path "/v1/pull", time 1,
      nonce 16 zero bytes, body "{}" (2 bytes)
message
  0000001366657272796b65792076312072657175657374
  00000004504f5354
  000000106170692e66657272796b65792e636f6d
  000000082f76312f70756c6c
  000000206e6837617270663666686d6f636f3378733371776271726b377a7a7461646962
  00000020636f7064737168676a6e6b6a6334726172646d32627632626d6b6834716a7861
  0000000000000001
  00000000000000000000000000000000
  44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
signature
  4c99d87d06dccaa9855d99d350f281c7cb20518560e7794afa629ef97bafb3c8
  60f74ccebf5af300a9aa73dbccc982518ed0c74088532a475a991f93d78ef40d
headers
  X-Fk-Account: nh7arpf6fhmoco3xs3qwbqrk7zztadib
  X-Fk-Device: copdsqhgjnkjc4rardm2bv2bmkh4qjxa
  X-Fk-Time: 1
  X-Fk-Nonce: 00000000000000000000000000000000
  X-Fk-Signature: 4c99d87d…f40d (the 128 hex characters above)

Signup proof of work

account   nh7arpf6fhmoco3xs3qwbqrk7zztadib, 22 bits
smallest valid PoW  4903928
hash      000000677b36df70bcc42abc5a7590d2a47e2292b0149574b2bf7c192c01a536

Key wraps use random HPKE encapsulation, so they have no fixed vector. Check your MLKEM768-X25519 implementation with the recovery public key above, and by unwrapping keys your own client wrapped.