> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rundesert.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Every call carries your workspace's API key. Where to find it, where to put it, and what happens when you change it.

Your workspace has one API key. It authorises every call to the workspace's API,
it starts with `dk_`, and it lives under **Settings → API** on the workspace,
right beside the URL it goes with.

<Note>
  The URL is the address and the key is the credential. Somebody holding only
  the URL gets a `401`; somebody holding the key can read everything this API
  serves. Keep it out of public repos, frontend code and shared documents.
</Note>

## Sending it

`Authorization: Bearer <key>` is the usual way, and it is what every HTTP client
already has a field for:

```bash theme={"system"}
curl https://www.rundesert.com/p/px_XXXXXXXX/api/automations \
  -H "Authorization: Bearer dk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
```

If the service you are calling from has already claimed its `Authorization`
header for its own auth — plenty of webhook consoles and integration builders do
— send the key in `x-desert-api-key` instead:

```bash theme={"system"}
curl https://www.rundesert.com/p/px_XXXXXXXX/api/automations \
  -H "x-desert-api-key: dk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
```

One form or the other. Both carry the same key, so there is nothing to gain by
sending both.

## When a call is refused

```json theme={"system"}
{ "error": "unauthorized" }
```

A `401` means the key was missing, malformed, or not this workspace's. Nothing of
yours ran: the check happens at the platform, before your workspace is woken or
your handler is reached, so there is no run and no log entry to go looking for.

Two things to check first, in this order:

1. **The key is the one on the settings page now.** If somebody generated a new
   one, the old string stopped working the moment they did.
2. **The key matches the URL.** Each workspace has its own key, and one
   workspace's key at another workspace's URL is refused exactly like a wrong
   one.

A wrong *address* answers `404` rather than `401`, so the two failures are easy
to tell apart: `404` means the `px_` id is wrong, `401` means the `dk_` key is.

## Generating a new key

The **Generate new key** button on the settings page replaces the key in place.
There is no grace period, no expiry window and no list of old keys — the previous
value is gone from the record, and the next call carrying it is refused.

That is the point of the button: a rotation that left the old key working would
not be a revocation. Use it when a key has been pasted somewhere it should not
have been, or when someone who had it should no longer have it.

Change your callers first if you can. Anything still sending the old key starts
failing immediately, and an automation that runs at 3am fails at 3am.

## File links are the exception

A `/~file` link needs no key:

```
https://www.rundesert.com/p/px_XXXXXXXX/~file/api/reports/report-2026-08-20.pdf
```

Those links are made to be clicked, out of an email or a chat message, and a
browser following a link cannot be asked to set a header. So a file link is its
own credential: anyone holding one can fetch that one file. Send them the way you
would send the file itself.

Everything else under your workspace's URL needs the key, including any endpoint
your agent writes for you.