Client tokens

Let a browser or an app send the photo to us directly, in your own design, without ever holding your secret key.

How it works

Your server mints a client token with its secret key. The token is good for one scan, for a few minutes, from the origins you name. The user’s device uses it to start the scan, and the answer carries a job_token that reads that one job for an hour. A copied token is worth one scan, not your balance. Minting is free.

Mint on your server, scan from the device

curl + JavaScript

# 1 · your server
curl -X POST https://spoken.fyi/api/v1/client-tokens \
  -H "Authorization: Bearer $SPOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "origins": ["https://yourapp.com"], "ref": "user-8841" }'
# → { "token": "ct_…", "expires_at": … }

// 2 · the browser or app
const r = await fetch("https://spoken.fyi/api/v1/scans", {
  method: "POST",
  headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
  body: JSON.stringify({ image_url, save: false }),
});
const { job_id, job_token } = await r.json();
// check GET /api/v1/scans/{job_id} with job_token

ref is your own id for the user or session — never a name or contact detail. Presenting the same token twice returns the same job instead of starting a second scan.