Authentication

One header on every request, and what happens when it's wrong.

Every request carries your API key in a header. There are no tokens to exchange, nothing to refresh, and no OAuth flow — the key is the whole scheme.

The header

Send the key as X-API-Key on every request:

X-API-Key: dk_live_…

The console's own API uses a bearer JWT instead. The two are entirely separate: a JWT will not authenticate against /v1, and this key will not authenticate against the console endpoints.

The header is CORS-allowed, so a browser can technically send it. That is a consequence of the header allowlist, not an invitation — see the API keys page for why you shouldn't.

Verifying it works

The cheapest way to check a key is to list workspaces. A working key returns 200 with a status of ok, even if you have no workspaces yet:

cURL

JavaScript

Python

curl "https://api.daneshyar.info/api/v1/workspaces/" \
  -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL"

When authentication fails

A missing key and an invalid key both return 403 — not 401. That surprises most clients, so branch on 403 rather than looking for 401:

403 — No X-API-Key header at all
403 — A key that doesn't match any app
404 — A valid key, but a workspace belonging to a different app

403

{
  "detail": "Invalid API key"
}

404

{
  "status": "failed",
  "message": "Workspace not found"
}

Note the two body shapes. Authentication failures come from the framework and carry detail; everything else comes from the view layer and carries status and message. Read both, in that order.

The header

Send the key as X-API-Key on every request:

X-API-Key: dk_live_…

The console's own API uses a bearer JWT instead. The two are entirely separate: a JWT will not authenticate against /v1, and this key will not authenticate against the console endpoints.

The header is CORS-allowed, so a browser can technically send it. That is a consequence of the header allowlist, not an invitation — see the API keys page for why you shouldn't.