API keys and authentication
Getting a key today
Free keys are self-serve:
- Create a free account with your email and a password, then sign in.
- Your account page opens. Press Get my free API key. Free keys are for personal, non-commercial use on the Free plan’s limits. Each account has one active free key.
- Copy the key straight away. It is shown once: IsoDelve stores only a SHA-256 hash of it, so a lost key can’t be recovered, only replaced. Regenerate on the account page revokes the old key and shows a new one; Revoke stops a key working immediately.
Paid plans (Hobby, Creator, Business and Platform) aren’t on sale yet: join the waiting list. Nothing is charged until checkout launches. For anything no plan covers, talk to us.
The Map Maker (coming soon) will not need a key; keys are only for calling the API from code.
What a key looks like
iso_live_7h2k9m4q8r1t6v3w5x0y2z4a6b8c0d1e (example only, not a real key)
iso_test_... (test keys use the same format)
- A prefix,
iso_live_oriso_test_, then 32 characters of lowercase letters and digits. The API checks the exact patterniso_(live|test)_[0-9a-z]{32}before it even looks the key up, so a key with a typo is rejected immediately. liveandtestkeys work the same way on the API today; the prefix just tells you (and your logs) which is which.- Each key carries a plan, which sets its size cap, rate limits and render allowance.
Sending the key
Send the key in the Authorization header with the Bearer scheme on every keyed request:
Authorization: Bearer iso_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Which endpoints need it:
| Endpoint | Key needed? |
|---|---|
GET /healthz |
No |
GET /v1/packs, GET /v1/packs/{ref}, pack files under /v1/packs/{id}/{version}/ |
No (public, so browsers can load sprites directly) |
POST /v1/maps (and /v1/maps/generate) |
Yes |
GET /v1/maps/{id}.json, GET /v1/maps/{id}.png |
Yes, and it must be the key that created the map |
GET /v1/usage |
Yes |
The key is not accepted as a query parameter or cookie, only in the header.
A request with a missing, malformed, unknown or revoked key gets the same answer (real response):
HTTP/1.1 401 Unauthorized
{"error":{"code":"unauthorized","message":"send Authorization: Bearer iso_test_... or iso_live_..."}}
Examples
curl (macOS, Linux, Git Bash):
export ISODELVE_KEY=iso_live_... # from your secret store
curl -s -H "Authorization: Bearer $ISODELVE_KEY" https://api.isodelve.com/v1/usage
Windows PowerShell (use curl.exe, not the curl alias):
$env:ISODELVE_KEY = "iso_live_..."
curl.exe -s -H "Authorization: Bearer $env:ISODELVE_KEY" https://api.isodelve.com/v1/usage
Node 18+:
const res = await fetch("https://api.isodelve.com/v1/usage", {
headers: { Authorization: `Bearer ${process.env.ISODELVE_KEY}` },
});
console.log(await res.json()); // { month, plan, maps, renders, rendersAllowance }
Python:
import json, os, urllib.request
req = urllib.request.Request("https://api.isodelve.com/v1/usage",
headers={"Authorization": "Bearer " + os.environ["ISODELVE_KEY"]})
print(json.load(urllib.request.urlopen(req)))
Keeping the key secret
The API allows cross-origin requests from any site (CORS *) so that browsers can load the public art packs. That also means a key placed in browser code would work for anyone who copies it. Treat the key like a password:
- Keep it on a server. Call
POST /v1/mapsfrom your backend, a serverless function or a bot process, then pass the map JSON to the browser. The browser only needs the public pack files to draw it. - Use environment variables or a secret manager. Never commit a key to git, paste it into a public Discord, or ship it inside a mobile or desktop app.
- Don’t put it in URLs you share. The starter viewer on the API host accepts
&key=for quick local testing only. - Use one key per app or environment so you can replace one without breaking the others.
If a key leaks
Keys can be revoked. Today that is done by hand: contact us and we will revoke the old key and issue a new one. Self-serve key management will arrive with billing.
Checking your key works
GET /v1/usage is the cheapest keyed call: it doesn’t generate anything. A real response from a development key:
{"month":"2026-11","plan":"dev","maps":5,"renders":6,"rendersAllowance":null}
rendersAllowance is null when the plan has no render cap. Next: Endpoints.