# Authentication

Every request carries your API key, as a bearer token.

```http
Authorization: Bearer $AGENTAL_API_KEY
Content-Type: application/json
```

- A missing or wrong API key answers `401 unauthorized`.
- A key may do only what it was made with: a preset or actions, some sandboxes or templates, a last day, and the addresses it may be used from. See [API keys](https://agental.io/docs/api-keys).
- Never print the API key, log it or write it into a file inside the sandbox.
- On your own computer, `npx agental@latest` signs in through your browser and keeps a key of its own for that computer. The `agental` command and the SDKs use it when `AGENTAL_API_KEY` is not set. See [Command line](https://agental.io/docs/cli).

## Secrets

Secrets are kept in [templates](https://agental.io/docs/templates). The variables and files of a sandbox's template, and any of its own, arrive in every command run in it. Use them by name and never print their values. Save them in the console under Templates, or with the API:

`PUT /v1/templates/{id}/secrets/variables/{name}`

```json
{"value":"…"}
```

Every account has a template named `default`, which a sandbox is on when it is made without naming one. `GET /v1/templates` lists them.

A key that only has to reach a few hosts can be [kept out of the sandbox](https://agental.io/docs/templates#keep-a-variable-out-of-the-sandbox): its commands see a stand-in, and the server the sandbox runs on puts the key in only on HTTPS requests to those hosts.

## Error shape

```json
{
  "error": {
    "code": "sandbox_not_running",
    "message": "The sandbox is stopped. Start it, then repeat the request."
  }
}
```

Decide what to do from `code`. `message` says why. See [Errors](https://agental.io/docs/errors) for the full list.

---

Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)