Guides

API tokens

An API token lets something other than you-at-the-dashboard talk to your platform — the astrodock CLI on your laptop, a CI job, or an AI agent that builds and deploys apps. Tokens are scoped, can be locked to specific apps, and are easy to revoke.

What tokens are for

You log in to the dashboard with your admin account. But the CLI and any automation need their own credential — that's the API token. You create one in the dashboard, then hand it to the CLI as ASTRODOCK_TOKEN. From then on, astrodock apply, deploy, set-secret, and friends authenticate with that token.

Tokens are not admin logins

A token carries a narrow scope for deploying and managing apps. It cannot manage users or other tokens — those stay behind your admin login. More on that below.

Create a token

In the dashboard, open the Tokens page and choose New token. Give it a name that says where it lives (e.g. "my laptop" or "ci-deploy"), pick its scope and any app restriction, and create it.

Scope

Tokens carry a scope. The one you'll use for the CLI and agents is deploy — it's what every deploy-related command checks for.

Optional: restrict to specific apps

By default a token can act on any app. You can narrow it to a list of app slugs so it can only touch those apps — anything else returns a "not scoped to app" error. This is the safest default for an agent that should only manage one app.

apps: ["crm", "gallery"]   # this token can only act on these two apps

Shown once

The token value (tk_…) is displayed only at creation. Copy it right away and store it somewhere safe — you can't view it again. Lost it? Just revoke it and create a new one.

Use it with the CLI

Point the CLI at your platform and give it the token via the environment:

export ASTRODOCK_URL="https://admin.example.com"
export ASTRODOCK_TOKEN="tk_paste-your-token-here"

astrodock apps        # confirms the token works
astrodock deploy:watch

An AI agent uses the exact same two variables. Hand the agent a token scoped to just the app it's working on, and it can apply, set secrets, and deploy on its own — without ever touching your users or other tokens. See Let an AI build & deploy.

Revoke a token

Back on the Tokens page, revoke any token to disable it immediately. Anything using it stops working at once, so revoke a token the moment a laptop is retired, a CI secret leaks, or an agent finishes its job.

What tokens can't do

Tokens are deliberately limited. A token cannot:

create, edit, or delete platform users (the people who log in to your apps), or
create or revoke other tokens.

Those actions require your admin login in the dashboard. So even a leaked token can't escalate into full control of the platform.

Security tips

Keep tokens tidy

One token per machine or agent. Don't share a single token around — separate tokens mean you can revoke just the one that's compromised.
Scope to specific apps whenever a token only needs to touch one or two apps.
Revoke when done. Finished a one-off job, or decommissioned a box? Revoke its token.
Treat tk_… like a password. Keep it out of git and shared chats; pass it through the environment, not command arguments.

Next steps

Hand an agent a scoped token: Let an AI build & deploy
How values are stored and gated: Secrets & environment variables
Walk the full deploy loop: Deploy your first app