Secrets · Guides
Manage service tokens
A service token lets a machine read one environment. Give every server, deploy and laptop its own, and revoke it when the machine is gone.
What a token can do
- It reads one environment, every value in it, Secret and Visible alike, and nothing else: no other environment, no other project.
- It changes nothing. The API only reads.
- It's shown once, when it's made. Only a hash of it is kept, so it can't be shown again.
- Every read is recorded in the project's audit log, with the token, the environment and how many variables it got.
Tokens look like st_….…: st_ and a public part, which the Tokens page shows to tell them apart, then a dot and the secret.
Make a token
On the project's Tokens tab, choose Make a token. Pick the environment it reads and, if you like, a label that says where it runs, such as vps-1 or deploy. Then Make token.
Making a token takes Admin in the project, and for a production environment, Admin in production. An environment has at most 10 active tokens at once.
Use it on a machine
The next page shows the token in the two lines a machine needs:
export MYBEAST_SECRETS_URL=https://services.my-beast.com/secrets
export MYBEAST_SECRETS_TOKEN=st_….…Copy it now, and keep it like a password
To check it on the machine, mybeast-secrets pull --out - prints the environment: its first line names the project and the environment. Then see Pull variables on a server.
Where each token stands
The Tokens page lists the tokens by environment, each with its label, when it was made and when it last read. A read is noted at most once a minute. Each token has one of these marks:
| Mark | What it means |
|---|---|
| Up to date | It has read since its environment last changed. |
| Behind | It last read before its environment's latest change: that machine doesn't have the change yet. Pull again, or restart what run started. |
| Never pulled | Made, but nothing has read with it yet. |
| Not pulled in 30 days | Nothing has read with it for a month. Revoke it if its machine is gone. |
| Revoked | A read with it is refused. |
The project's Overview counts the ones that need a look: behind, never pulled, or idle. A token whose environment was removed at id is listed apart, as No environment: it reads nothing, and an admin can revoke it.
Rotate a token
- Make a new token for the same environment.
- Put it on the machine in place of the old one.
- When the new one has read, revoke the old one.
Nothing stops working in between.
Revoke a token
Revoke is behind the token's ⋯, and asks first. A machine still using it is refused from its next read: a pull leaves its .env as it was, and run doesn't start its command. A revoked token stays revoked: make a new one to replace it. Revoked tokens are folded at the foot of the page.
Revoking takes Admin in the project, and for a production environment, Admin in production.