Secrets · Reference

API

One endpoint: a service token reads its environment, as JSON, a .env file or shell lines. It's what mybeast-secrets uses, for anything that can make an HTTPS request.

Base URL

https://services.my-beast.com/secrets/api/v1

HTTPS only. MYBEAST_SECRETS_URL, as the Tokens page gives it, is the part before /api/v1.

Authentication

Every request carries a service token as a bearer token:

Header

Authorization: Bearer st_….…

The token decides what is read: its own project and environment, and nothing else. Make one per machine on the project's Tokens page: see Manage service tokens.

Keep the token off command lines

curl -H "Authorization: Bearer …" puts the token where other users' ps can see it. Hand it to curl on its standard input, as below and as mybeast-secrets does.

Read an environment

GET/api/v1/secrets

Terminal

printf 'header = "Authorization: Bearer %s"\n' "$MYBEAST_SECRETS_TOKEN" |
  curl --fail --silent --show-error --config - \
  "$MYBEAST_SECRETS_URL/api/v1/secrets"

Parameter	What it does
`format`	`json` (the default), `env` for a `.env` file, or `shell` for `export` lines. Anything else is refused with `422`.

Every value in the environment comes back, Secret and Visible alike, sorted by name. The answer is never cached (Cache-Control: no-store, private), and every read is recorded in the project's audit log, with the token and the format.

JSON

200 OK

{
  "project": "shop",
  "environment": "production",
  "version": 12,
  "variables": {
    "APP_NAME": "My Shop",
    "APP_URL": "https://shop.example.com",
    "DB_PASSWORD": "it's $ecret",
    "EMPTY": ""
  }
}

Field	What it is
`project`	The project's short name.
`environment`	The environment's name.
`version`	The number of the environment's latest change, `0` before the first. It goes up with every change, so it tells you whether anything changed since your last read.
`variables`	Every variable, name to value. Values are strings; an empty one is `""`.

.env

200 OK · text/plain

# MyBeast Secrets · shop/production · change #12 · 4 variables · 27.10.2026 14:05 UTC
APP_NAME='My Shop'
APP_URL=https://shop.example.com
DB_PASSWORD="it's \$ecret"
EMPTY=

The file mybeast-secrets pull writes: a first line that says what it is, then NAME=value lines, quoted where needed. Laravel, Docker Compose, Node's dotenv and bash's source all read the same values back. See What the file holds.

Shell

200 OK · text/plain

export APP_NAME=$'My Shop'
export APP_URL=$'https://shop.example.com'
export DB_PASSWORD=$'it\x27s \x24ecret'
export EMPTY=$''

One export NAME=$'…' line per variable. Every byte other than letters, digits, a space and _ . / : @ % + , = - is written as \xHH, so a line can only ever export its variable. mybeast-secrets run reads this format, checking each line's shape and decoding it without running it.

Errors

Errors come back as JSON with a message:

Status	When
401	No token, a mistyped or revoked one, or one whose environment was removed. The body is `{"message":"unauthenticated"}`.
422	A `format` other than `json`, `env` or `shell`.
429	Too many reads: see Rate limits. `Retry-After` says how many seconds to wait.

A refused read is not recorded as a read, and nothing about the environment comes back.

Rate limits

120 reads a minute per token,
300 reads a minute from one address, across its tokens.

A deploy reads once, and mybeast-secrets run once per start, so these are far above what a machine needs. Reads are not counted towards a package.