API reference and test vectors
Every endpoint of api.ferrykey.com, and values to check your implementation against.
Contents
- Conventions, errors and limits
- Endpoints: /v1/account, /v1/log/append, /v1/log, /v1/commit, /v1/snapshot, /v1/pull, /v1/push-token, /health
- Test vectors
Conventions
- Base URL
https://api.ferrykey.com. HTTPS only. - Every API call is a
POSTwith a JSON body (Content-Type: application/json). Responses are JSON withCache-Control: no-store. - Every call sends
X-Fk-Protocol: 2. Without it, or with a lower number, the answer is 409upgrade_required. - Signed calls also send
X-Fk-Account,X-Fk-Device,X-Fk-Time,X-Fk-NonceandX-Fk-Signature, made as in API requests. The signer is a current member device, orroot(the recovery words) where noted. - Field names are exactly as shown, case included. The server ignores fields it doesn’t know.
- Byte strings (keys, signatures, blobs, wraps) are standard base64 with padding.
- 32-byte hashes (
Prev,EntryHash,LogHash,HeadHash,BlobHash, tombstoneFingerprint) are JSON arrays of 32 numbers from 0 to 255, not strings. - Numbers are plain JSON integers. An absent list may be sent or returned as
null. - Collection names follow the rules in Collections;
logis reserved and refused. - Any signed call can also fail with
unauthorized,clock_skew,device_removed,no_account,busyorinternal, and withrequest_too_bigon the small-body endpoints.
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.
| Status | Code | Meaning and what to do |
|---|---|---|
| 400 | bad_request | Malformed request. Don’t retry unchanged. |
| 400 | invalid_entry | A log entry broke a membership rule. The message says which. |
| 400 | pow | Signup proof of work too weak. |
| 400 | invalid_head, invalid_statement | Bad head or snapshot statement signature, scope or chain. |
| 401 | unauthorized | Missing or bad signature headers, unknown device, bad signature, or a reused nonce. |
| 401 | clock_skew | The device clock is more than 5 minutes off. |
| 403 | device_removed | This device was locked out. Stop syncing and tell the user. |
| 403 | forbidden | The device may not use this collection. |
| 403 | too_many_devices | The account already has 20 devices. |
| 404 | no_account | No such account (never created, or deleted after 12 months unused). |
| 404 | no_push | Live updates aren’t available. |
| 409 | conflict | Someone else wrote first. Pull, merge, re-sign and retry. |
| 409 | exists | The account already exists. |
| 409 | log_changed | The membership log moved on. Read it again and retry. |
| 409 | rotation_required | A commit while a rotation is pending, or a write that isn’t in the current epoch. Rotate if you can, otherwise wait. |
| 409 | snapshot_required | Upload 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. |
| 409 | upgrade_required | Protocol version no longer supported (also sent for a commit whose head isn’t version 2, or a snapshot without a statement). Stop and update. |
| 413 | too_big, request_too_big | Blob or body over the limit. |
| 429 | rate_limited | Too many new accounts from this network today. |
| 500 | internal | Server fault. Back off and retry. |
| 503 | busy, read_only | Overloaded, or writes paused for maintenance. Back off and retry. |
Limits and retention
| Limit | Value |
|---|---|
Request body: /v1/log, /v1/pull, /v1/push-token | 64 KiB |
Request body: /v1/account, /v1/log/append | 1 MiB |
Request body: /v1/commit, /v1/snapshot | 8 MiB |
| Envelope blob (commit or snapshot), all collections | 5 MiB (5,242,880 bytes) |
| Devices per account | 20 |
| Collections per account | 16 |
| Signup proof of work | 22 bits |
| New accounts per network (IPv4 /24 or IPv6 /64) per UTC day | 5 |
| Request clock skew | ±5 minutes |
| Pull response | up to 200 commits, about 8 MiB of blobs, 2,000 skipped heads |
| Commits and snapshots superseded by a newer snapshot | deleted within about 7 days (their signed heads are kept) |
| Accounts with no signed request from any device | deleted after 12 months |
| Live-update token | 30 minutes |
POST /v1/account
Creates an account. Unsigned: the entries sign themselves.
{"Init": Entry, "First": Entry, "PoW": 4903928}
Init: the Init entry (seq 1).First: an Add (seq 2) of the creating device, signed byroot.PoW: a number such that SHA-256("ferrykey v1 signup pow"| account ID |PoWas u64 big-endian) starts with at least 22 zero bits. The label and account ID are raw ASCII with no length prefixes. Expect about 4 million hashes.
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:
- The device may use the collection (
forbidden) and the blob is at most 5 MiB (too_big). - No rotation is pending and
Epochis the current epoch (rotation_required). The blob’s header epoch equalsEpoch(bad_request). Head.Versionis 2 (upgrade_required).Head.Collectionmatches,Head.Seqis the current head + 1 andHead.EntryHashis SHA-256 of the blob (conflict).Head.LogSeqandHead.LogHashname the current log andHead.Epochthe current epoch (log_changed).- If the previous commit is in an older epoch, the latest snapshot must be in the current epoch at the current head (
snapshot_required). - If the collection’s history starts with protocol 1 heads and it has no signed snapshot, a signed snapshot is needed first (
snapshot_required). - 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:
- Valid collection name the signer may use (
bad_request,forbidden); blob at most 5 MiB (too_big). - 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). Seqis the current head (conflict). It is 0 for a collection with no commits.- A statement is present (
upgrade_required). Its collection, seq andBlobHashmatch (bad_request). Its log point and epoch are current (log_changed).HeadHashis the hash of the head atSeq, or zero whenSeqis 0 (conflict). It is signed by the caller, withDeviceIDset to the caller’s device ID orroot(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}
Since: the highest commit the device has applied (0 for nothing).HeadsFrom: the highest seq whose head the device has verified (at leastSince). On a device’s first sync, send exactly 262 (4611686018427387904) to ask for no skipped heads.HeadSeq: the collection’s current head.
How the server answers:
- 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 inHeads, 2,000 at most. If they don’t all fit, the response has onlyHeadsandMore: true; ask again with a higherHeadsFrom. - Once the heads reach it,
Snapshotis set andCommitsstarts 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. - Otherwise
Commitsstarts atSince+ 1. Commitsholds up to 200 commits and stops after about 8 MiB of blobs (always at least one).Moreis true when there are more: pull again with the newSince.
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
- Secret 32 ×
00→abandon× 23, thenart. - Secret 32 ×
ff→zoo× 23, thenvote. - Secret 32 ×
7f→legal winner thank year wave sausage worth useful× 3, with the last wordtitleinstead ofuseful. abandon× 24 → rejected (bad checksum).- Kit code for the zero secret:
ferrykey:v1:followed by 52 ×A.
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.