Ed25519 signed writes for agent APIs: canonical bytes, replay windows, rotation

Not specified by the original author.

Ed25519 signed writes for agent APIs

TL;DR

The agent holds a private signing key and signs a canonical string built from the request: method, path, a timestamp, a nonce, and a hash of the body. The server verifies the signature with the registered public key, checks the timestamp window and nonce freshness, and only then applies the write. Signing proves which agent sent the exact bytes received, and it travels safely through logs and intermediaries that a bearer credential cannot.

When to use this

• An API offers or requires signed writes and you are implementing the client side.
• You are designing write authentication for an agent API and comparing signatures with your bearer credential
• Writes pass through queues, relays, or gateways where a bearer credential would be exposed to intermediaries.

When not to use it

• The API only supports bearer credentials; adding signatures the server does not verify adds cost and no security.
• The client cannot protect a private key at rest. A leaked signing key is a full identity compromise until rotation.

Steps

1. Generate the keypair once, on the operator's machine, and register only the public key with the API. Success check: the service can show you the fingerprint of the public key it has on file, and it matches yours.
2. Build the canonical string for each write. A workable shape is five lines joined by newlines: the HTTP method, the exact request path, the current Unix timestamp, a fresh random nonce, and the hex digest (SHA-256) of the exact request body bytes. Success check: signing the same request twice in a test harness produces strings that differ only in timestamp and nonce.
3. Sign the canonical string with the private key and send the signature, the timestamp, the nonce, and your key identifier in headers, alongside the unchanged body. Expected behavior: the server accepts a well-formed signed write within the timestamp window, typically a few minutes.
4. Handle the three signature failures distinctly. A signature mismatch means your canonical string differs from the server's, so log both strings locally and diff them. A stale timestamp means clock skew or a slow queue, so resync and retry once with a fresh signature. A reused nonce means a replay or a client bug, so treat it as an error, never as a retry signal.
5. Rotate by registering the new public key before retiring the old one, and overlap briefly. Success check: writes signed with either key succeed during the overlap window, and only the new key works after it closes.

Variants

Signed writes plus idempotency keys

Signatures prove origin; they do not deduplicate. Send an Idempotency-Key header with the write as well, signed as part of the canonical string, so a retried write is both authenticated and applied once.

Detached vs attached signatures

A detached signature travels in headers and leaves the body untouched, which suits JSON APIs. An attached or enveloped signature wraps the payload and suits message buses. Pick based on what the transport already parses, not on preference.

Why signatures over bearer credentials

A bearer credential is a secret that every intermediary sees and any leak replays until revocation. A private signing key never leaves the agent, each signature is bound to one request's exact bytes, and the timestamp plus nonce bound the replay window to minutes. The cost is canonicalization discipline: two implementations that serialize the same request differently will disagree on the signature.

Edge cases

• Sign the bytes you send, not the object you built. Re-serializing JSON, reordering fields, or changing whitespace after signing invalidates the signature.
• Unicode in paths or bodies must be hashed as the exact UTF-8 bytes on the wire.
• Clock skew is the top cause of mysterious rejections in sandboxed agents. Log your timestamp and the server's reported time on every failure.
• Never sign a blank or templated body and fill it in later. The signature must be the last step before sending.

General protocol guidance based on RFC 8032 (Edwards-Curve Digital Signature Algorithm). No Vectle-specific claim is made: as of 2026-10-15 the published Vectle API documents Bearer credentials and cookies, not request signing, per https://vectle.com/api/v1/openapi and https://vectle.com/llms.txt. Included in the evaluator canon because signed writes are a standard design an agent meets when comparing write-auth schemes across agent APIs.