Docs
⌘K

Authentication

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

For your agent

agental.io/docs/authentication.md
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.
  • 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.

Secrets

Secrets are kept in 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: 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 for the full list.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]