ASTRODOCK documentation Home GitHub

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

Give each app repo its own credentials file. In the repo root, create .env.astrodock with two lines:

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

The CLI reads the file from the directory you run it in, so from inside the repo astrodock apply, deploy and friends just work — no shell setup. Add .env.astrodock to the repo's .gitignore; the CLI refuses to run if git tracks the file. When ASTRODOCK_URL / ASTRODOCK_TOKEN environment variables are set they win over the file, which is what you want in CI.

astrodock apps        # confirms the token works
astrodock deploy:watch

One repo, one narrowly-scoped token. Resist putting a broad token in your shell profile and sharing it between projects: a per-app file means a leak, a paste into the wrong window, or an over-eager tool can only ever reach the one app that token was scoped to.

An AI agent works the same way — and never needs to see the token at all. It runs the CLI in the repo, the CLI picks the credentials up from the file, and the value itself stays out of the agent's conversation. 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