IsoDelve

Home › Developer guide › API keys and authentication

API keys and authentication

Developer guide · updated

Getting a key today

Free keys are self-serve:

  1. Create a free account with your email and a password, then sign in.
  2. 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.
  3. 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_ or iso_test_, then 32 characters of lowercase letters and digits. The API checks the exact pattern iso_(live|test)_[0-9a-z]{32} before it even looks the key up, so a key with a typo is rejected immediately.
  • live and test keys 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/maps from 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.