API reference

Consume a secret

Retrieve the encrypted envelope once. Retrieval and consumption are one atomic operation.

POST/secrets/{id}/consume

Request#

Use the reference returned at creation. Send no body, encryption key, or deletion token. JavaScript uses variables from Quickstart.

JavaScript

// Run only after an explicit Reveal click. Never automatically retry.
const consumeResponse = await fetch(
  `${api}/secrets/${encodeURIComponent(id)}/consume`,
  { ...requestOptions, method: 'POST', signal: AbortSignal.timeout(15000) },
)
if (consumeResponse.status !== 200) {
  throw new Error(`Retrieval failed (${consumeResponse.status})`)
}
const { envelope: receivedEnvelope } = await consumeResponse.json()
const revealedText = await decryptText(receivedEnvelope, keyFragment)
// Render as text, not HTML. Keep it in memory only.

cURL

# Set ID to the reference of a disposable secret.
# This consumes it. Never retry automatically.
curl -i -X POST "https://api.xasha.site/secrets/$ID/consume"

Response#

200 OK. Decrypt locally.

json

{
  "envelope": {
    "version": 1,
    "iv": "<original base64url IV>",
    "ciphertext": "<original ciphertext and tag>"
  }
}

Unavailable secrets#

Missing, malformed, expired, deleted, and consumed references return the same 404.

json

{
  "error": {
    "code": "SECRET_UNAVAILABLE",
    "message": "This secret is no longer available."
  }
}

Never automatically retry#

A lost response, service error, or failed decryption does not establish that consumption did not happen. Do not replay the request. Ask the sender to create a new secret.