# Keys and roles

> Your bot holds one key, and it can only ask. Your people hold the keys that change things. reTrade signs its answers with its own.

Status: In development. Not released yet; names and formats may change. Web page: https://retrade.app/docs/concepts/keys

## The four kinds of key

Who holds each key, and what it can do:

| Key | Id | Who holds it | What it can do |
|---|---|---|---|
| Executor key, your bot’s | `exk_<mode>_<ULID>` | Your agent’s machine. reTrade only ever sees its public half. | Ask for decisions, report what happened, read the status and the log, and engage a stop. Never release a stop or change limits, modes or keys. |
| Admin keys, two or more | `adm_<ULID>` | Your people. | Change limits, modes and keys, and engage and release stops, through the admin API and command line (in development). |
| Daily decision keys | `dk_<env>_<YYYYMMDD>` | reTrade, one a day (UTC). | Sign every answer, receipt and log head. |
| Root key | `root` | reTrade, kept offline. | Signs the list of decision keys. Your SDK pins its public half. |

## Your bot’s key

Python:

```shell
retrade keygen executor.pem
```

TypeScript:

```shell
npx retrade keygen executor.pem
```

This writes an Ed25519 private key to `executor.pem`, in unencrypted PKCS8 PEM, readable only by you (mode 0600), and prints its public half. It never overwrites a key file, and a key made by either SDK works with the other. An admin registers the public half for one mode and sends back its id; it works at once.

The SDK refuses a key file other users can read. Anyone holding the file can ask for decisions as your agent, so keep it out of your repository, your logs and your images. On a server or in a container, mount it as a file readable only by the bot’s user: the SDK reads the key from a path, not from an environment variable.

The mode in the id (`enforce`, `shadow` or `test`) is the mode of every order the key asks about. A decision key’s `env` is `live` for enforce and `nonlive` for shadow and test.

## Admin keys

A tenant has at least two admin keys. A new admin key works 24 hours after it’s added, or at once during first setup. Admin keys sign every change to limits, modes and keys, and release stops.

If your people lose them, only reTrade’s operator can help: after checking who is asking, outside reTrade, it adds one new admin key with `retrade-server admin-key-recover`. That key works only 24 hours later, and the change is written to your log at once, where any admin who still holds a key sees it and can revoke the new key before it works. `retrade-admin keys list` warns when you have exactly two admin keys.

## reTrade’s keys

Each daily decision key is valid from 00:00 UTC on its day to 00:05 the next day, and stays on the list forever, so an old answer can always be checked. The SDK fetches the list from `GET /v1/keys` and checks it against the pinned root key.

The root public key is 43 characters of base64url. reTrade gives it to you when your tenant is set up; it isn’t published on this site yet. Pass it as `root_key` (`rootKey`); the SDK never fetches it.

## Signed requests

The SDK signs every request with your executor key, so reTrade knows which bot is asking. You don’t sign anything yourself. The headers and signed lines are in the [API reference](https://retrade.app/docs/reference.md#request-signing).