curl --request GET \
--url "https://cache.example.com/cache/messages/did%3Aopenpayload%3A1111111111111111111111" \
--header "X-Service-Id: did:openpayload:1111111111111111111111#cache" \
--header "X-Cache-Endpoint: https://cache.example.com" \
--header "X-Key-Id: did:openpayload:1111111111111111111111#signing" \
--header "X-Timestamp: <current-RFC3339-timestamp>" \
--header "X-Nonce: <unique-random-nonce>" \
--header "X-Signature: <base64-signature>"
Cache API
Get cached messages
Retrieve pending encrypted envelopes for a recipient using a signed Cache access proof
curl --request GET \
--url "https://cache.example.com/cache/messages/did%3Aopenpayload%3A1111111111111111111111" \
--header "X-Service-Id: did:openpayload:1111111111111111111111#cache" \
--header "X-Cache-Endpoint: https://cache.example.com" \
--header "X-Key-Id: did:openpayload:1111111111111111111111#signing" \
--header "X-Timestamp: <current-RFC3339-timestamp>" \
--header "X-Nonce: <unique-random-nonce>" \
--header "X-Signature: <base64-signature>"
This endpoint returns encrypted messages waiting for one recipient DID. It does not decrypt them.
Because a DID is public, the DID alone is not authorization. Your client must sign a Cache retrieval proof with an Ed25519 verification method authorized by the recipient’s
Sign those bytes with the authorized Ed25519 private key, then Base64-encode the signature.
The timestamp may be ISO-8601, epoch milliseconds, or epoch seconds and must fall within the Cache’s permitted clock skew. Never reuse a nonce with the same operation, DID, and key.
This response example shows ordinary DID-service fall-through. A policy-delivered envelope may also contain opaque network-managed policy provenance. Treat it as transport metadata; do not modify it or resubmit it as client authorization.
Proof operation:
Proof device: empty
Proof subject:
OpenPayloadCacheService.
Build the signed proof
Construct this exact UTF-8 string. Do not add a trailing newline:openpayload:cache:retrieval-proof:v1
operation=pull
did=did:openpayload:1111111111111111111111
device_id=
service_id=did:openpayload:1111111111111111111111#cache
cache_endpoint=https://cache.example.com
key_id=did:openpayload:1111111111111111111111#signing
timestamp=<current-RFC3339-timestamp>
nonce=<unique-random-nonce>
subject=*
Request
string
required
The recipient DID.
string
required
The authorized
OpenPayloadCacheService ID.string
required
The exact public Cache endpoint bound into the signature.
string
required
The authorized Ed25519 verification-method ID.
string
required
The signed timestamp.
string
required
A new replay-resistant nonce.
string
required
Base64 Ed25519 signature over the exact proof text.
curl --request GET \
--url "https://cache.example.com/cache/messages/did%3Aopenpayload%3A1111111111111111111111" \
--header "X-Service-Id: did:openpayload:1111111111111111111111#cache" \
--header "X-Cache-Endpoint: https://cache.example.com" \
--header "X-Key-Id: did:openpayload:1111111111111111111111#signing" \
--header "X-Timestamp: <current-RFC3339-timestamp>" \
--header "X-Nonce: <unique-random-nonce>" \
--header "X-Signature: <base64-signature>"
Response
200 Response
{
"count": 1,
"messages": [
{
"message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
"recipient": "did:openpayload:1111111111111111111111",
"expires_at": "2026-07-25T16:30:00Z",
"chunked": false,
"envelope": {
"message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
"to": "did:openpayload:1111111111111111111111",
"timestamp": "2026-07-24T16:30:00Z",
"expires_at": "2026-07-25T16:30:00Z",
"payload": {"ciphertext_b64":"<encrypted-message>"}
},
"proof": {
"event_type": "retrieval"
}
}
]
}
After retrieval
- Verify the envelope and any sender signature your application requires.
- Store it safely on the recipient device.
- Decrypt it locally.
- Record the Cache endpoint from which this copy was retrieved.
- Acknowledge it at that Cache only after you no longer need the encrypted copy.
details.accepted_caches and Archive endpoints in details.accepted_archives. Those lists do not include later accepts after a Forward step and are not embedded in the stored envelope for the recipient. If the recipient retrieves replicas from more than one Cache, it acknowledges each copy at the Cache that returned it.
Straight to the point
GET /cache/messages/{did}
pullProof device: empty
Proof subject:
*