Sending the header
You present your credential by sending the envelope as a single HTTP header: X-MotherShy.
The header
The envelope is compact, single-line JSON (HTTP headers can't contain newlines):
json
{"cert":{"path":"agents/alice","pub":"<b64>","sig":"<b64>"},"req":{"agent":"<b64>","site":"example.com","nonce":12345,"ts":1728000000,"amt_microusd":5,"window":300},"sig":"<b64>","cap":{"v":1,"id":"cap-1","holder":"<b64>","aud":"example.com","actions":["retrieval"],"cap_microusd":1000,"issued_at":1728000000,"expires_at":1728003600,"policy_receipt":"receipt-1","verification_mode":"offline","sig":"<b64>"}}Send it:
bash
curl -H "X-MotherShy: $(cat envelope.json | tr -d '\n')" https://example.com/Field order matters
The request and capability are signed over a canonical serialization with a fixed field order. If you re-serialize with different ordering, the signature won't verify. The exact byte layouts are in The wire format — use them verbatim, never JSON.stringify blindly.
Request fields
| Field | Meaning |
|---|---|
agent | Your base64 public key — must equal cert.pub |
site | The site you're accessing (the audience) |
nonce | Anti-replay nonce (a JS safe integer) |
ts | Unix seconds (anti-replay window) |
amt_microusd | The amount you're authorizing (≤ your budget) |
window | Hour bucket |
Anti-replay
The wall rejects requests older than the replay window or from the future (clock-skew tolerance). The nonce must be a JS safe integer (≤ 2^53−1) — a larger value round-trips differently across languages and is rejected fail-closed.
Next
- Error reference — what each response means.
- The wire format — exact byte layouts.