- The command line tool.
trusset-kycseals, signs, sends and revokes for you. See the verifier walkthrough. - Your own implementation. The envelope uses HPKE as standardised in RFC 9180 and Ed25519 signatures. This page specifies the format completely, so a stock HPKE library is enough.
Base Path
sourceId and the API address both come from the invite the bank gave you. Each source has its own inbox, and one inbox delivers to one bank instance.
Authentication
Every request carries the token from the invite as a bearer token:401 UNAUTHORIZED. So does an unknown sourceId and a source the bank removed, with the same message, so the answer does not reveal which of them applies. When the bank issues a new invite, the old token stops working at once.
The invite
The bank creates your source and hands you one string:Keys
A key ID is the first 16 hex characters of SHA-256 over the raw public key bytes. A fingerprint is the first 32 hex characters of the same hash, in 8 groups of 4 separated by a space, for example
b961 9d9b e69e d903 c31c 6f1a f3c6 a7d2.
You send the bank your signing public key once. The bank registers it on your source and pins it in its own tool. Trusset never needs your private key, and no endpoint accepts one.
Envelope format
An envelope has four parts: a clear header, the HPKE encapsulated key, the ciphertext and a signature. Build them in this order.1. The record document
The record document is what the bank reads after decryption. It is a JSON object serialised to UTF-8 bytes, calledP below:
An attachment
name is a plain file name of at most 120 characters: no path separator, no leading dot, unique within the record in any letter case. mediaType is a lowercase type/subtype.
From P you derive three values:
2. The header
The header is the only part Trusset can read. It carries exactly these 13 keys and no other. Write them in this order:
Every value except
v is a string, and each one has a fixed form. The header has no free-text key and none can be added. A header with a missing or an extra key is refused.
Compact JSON. The header bytes are the UTF-8 bytes of the JSON with no whitespace and no duplicate keys. They must equal what JavaScript produces with JSON.stringify(JSON.parse(text)). Anything else is refused with VALIDATION_ERROR. In Python, json.dumps(header, separators=(',', ':'), ensure_ascii=False) produces this form. In Go, disable HTML escaping in the encoder.
The header bytes are used three times, always the exact same bytes: as the HPKE associated data, inside the signature, and on the wire as base64url without padding. They are at most 2,048 bytes.
3. Sealing
Seal with HPKE, RFC 9180, base mode, single shot:
The result is
enc, the 32-byte encapsulated key, and ciphertext, the AES-256-GCM output with its 16-byte tag appended. One message is sealed per context, so the sequence number is 0.
4. The signature
The delivery body
The ciphertext limit covers the whole record document with its attachments. Attachments are base64 inside the document, so about 4.5 MiB of files fit in one record. Describe Inbox reports the limit as
limits.maxCiphertextBytes.
Timestamps
Every timestamp has exactly the formYYYY-MM-DDTHH:mm:ss.sssZ, in UTC with milliseconds, as JavaScript’s toISOString() writes it. On delivery the header must satisfy all of these, measured against Trusset’s clock, which Describe Inbox returns as serverTime:
What Trusset checks
On delivery Trusset checks the header’s form and timing, the sizes, thatsourceId names your inbox, that profileKey is the one the bank set for you, that recipientKeyId names the bank’s current key, and the signature against the signing key the bank registered for your source.
Trusset cannot check anything inside the ciphertext. The bank’s tool does that after decryption: it verifies the signature on the envelope and innerSignature against the key the bank pinned, and compares the record document with recordDigest, openCommitment, the fields repeated in the header and every attachment hash. An envelope that fails there is rejected by the bank with BAD_SIGNATURE, DIGEST_MISMATCH or UNDECRYPTABLE, which you read from Get Delivery Status.
Sending twice
Posting the exact same envelope again is safe. It answers200 with replayed: true and the record it already created, and stores nothing new. Two other cases are refused:
A record that has to be delivered again, for example after the bank rejected it, is sealed again with a new
envelopeId, openProof and nonce. That also gives it a new recordDigest.
Revocations
You revoke a record you delivered with a signed statement. Its header carries exactly these 8 keys, as compact JSON under the same rules:revocationId is 16 random bytes as 32 lowercase hex characters. reason is EXPIRED, WITHDRAWN, SUPERSEDED, INVALID or OTHER. issuedAt follows the same rule as on a delivery.
{ "header": "<base64url>", "signature": "<base64>" }. See Revoke Record.
What happens to a record
Trusset deletes the ciphertext when the bank opens or rejects the record, when you revoke it, when
validUntil passes, and after 30 days uncollected. The header stays.
Response envelope
data and error, with the unused one null. On failure, error carries code and message, and details.field where one field is at fault. Responses are sent with Cache-Control: no-store.
Errors every route can return
Rate limits
Requests without an API key count against the per-IP limit of 100 requests per minute described on Rate Limits. The inbox adds two of its own: 240 requests per minute for each source, and 20 failed authentications per 10 minutes for each IP address, after which a further failed attempt answers429 instead of 401.
A delivery is also refused with 429 INBOX_FULL while too many of your records wait unopened at the bank. That is not a rate limit: retrying does not help until the bank opens records. See Deliver Record.
