Authentication

On this page: OSS admin secret (Community / no plugins) → Licensed security (multi-user Access Tokens). Day-to-day RBAC and audit deep-dives live under Advanced Management.

Can OSS use --token?

Yes. OSS has no sk-… Access Tokens, but when you set a non-empty auth_secret in conf/super.toml, that string is the Bearer credential for:

• super --token <secret> …
• export SUPER_TOKEN=<secret>
• super login <secret>
• Dashboard login
• Authorization: Bearer <secret>

super --token 'your-auth-secret' list

--token only means “send this string as Bearer”; it does not mint or imply an sk-… token.

OSS admin secret

Rules

There is no on-disk auth.key. The only OSS secret is auth_secret in config. Because the file holds a live credential, keep it owner-readable only:

chmod 600 conf/super.toml

superd warns at startup if auth_secret is set and the config is group/world-readable.

# conf/super.toml — enable auth (also required for non-loopback binds)
[server]
auth_secret = "your-own-long-random-string"
host = "127.0.0.1"   # default; use 0.0.0.0 only with auth_secret set

Use the secret

SECRET='your-own-long-random-string'   # same as auth_secret in toml

super login "$SECRET"
super list

super --token "$SECRET" list
export SUPER_TOKEN="$SECRET"

curl -H "Authorization: Bearer $SECRET" \
  http://127.0.0.1:9002/api/v1/programs

Dashboard: open /, paste the same string when prompted.

Licensed deployments require security

Every subscription includes the security plugin at no extra charge. If [license].key verifies successfully, superd refuses to start unless:

1. security is listed in the signed license claims (re-issue legacy keys that omit it).
2. security.so / security.dylib loads successfully from $SUPER_ROOT/plugins/.
3. auth_secret is set in conf/super.toml (Admin Bearer for bootstrap).
4. HTTP auth middleware is active (the security plugin exports authenticate).

Other licensed plugins (ui, notify, isolation, …) load only after these checks pass. OSS deployments (no valid license) are unchanged.

Invalid or incompatible license key

If [license].key is set but verification fails (bad signature, expired with retain_grants_after_expiry = false, or superd version outside the signed range), superd does not treat the deployment as licensed:

The SUPER_LICENSE / SUPER_LICENSE_STRICT env overrides are documented in Environment Variables.

Production subscription templates ship with strict = true. Fix the key, renew, or remove licensed-only configuration to run in OSS mode.

Troubleshooting license verification

When startup, super check, or super doctor reports a bad or incompatible license, try these steps locally (no daemon required for check / keyring):

1. super check — re-validates conf/super.toml, including the license string and licensed-mode requirements.
2. super doctor — runs the same config check, then probes a running daemon; prints a Verifying keys line (embedded signing key ids in this CLI binary).
3. super keyring — lists every verifying key id (kid) compiled into this build; use --json for scripts.

Typical messages and what to do:

Official release binaries may embed more verifying keys than a local cargo build from git alone. Compare against the release you actually run in production, not only a dev build.

Enabling Authentication (Subscription)

1. Add a valid [license].key in conf/super.toml (must authorize security — included with every subscription).
2. Install security.so from your subscription delivery package into $SUPER_ROOT/plugins/ (required for startup).
3. Set [server].auth_secret in super.toml (required for startup):

# super.toml (subscription)
[server]
auth_secret = "my-super-secure-root-password"

Once the security plugin is active:

1. All API requests require an Authorization: Bearer <token> header (except /health and the docs whitelist: /api/docs, /api/v1/openapi.json, SPA / + /assets). /metrics requires Bearer when auth is on — configure Prometheus with authorization.credentials.
2. The Dashboard prompts for an Access Token when auth is required (or the admin/auth_secret string for bootstrap).

Bootstrap with auth_secret

Sign in with config auth_secret (Dashboard or super login), then create Access Tokens. Creating a token does not end the current root session:

curl -X POST http://127.0.0.1:9002/api/v1/auth/tokens \
  -H "Authorization: Bearer my-super-secure-root-password" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-bot","role":"operator"}'

By default auth_secret stays usable even after tokens exist (with a Dashboard warning). Prefer generated sk-... tokens for day-to-day access.

The Access Tokens page in the Dashboard (Account menu) appears when the security and ui plugins are loaded. You can always manage tokens via the HTTP API below without that UI.

Optional: disable auth_secret

An Admin (including a root session still using auth_secret) can explicitly disable config auth_secret after at least one Admin Access Token exists:

• Dashboard → Access Tokens → Disable auth_secret (requires ui + security)
• Or POST /api/v1/auth/secret/disable

State is persisted in $SUPER_ROOT/data/auth_settings.json. While disabled, Bearer/auth_secret login is rejected.

Recovery: revoke all Admin Access Tokens — auth_secret is re-enabled automatically. Startup still requires auth_secret to be set in super.toml.

If data/tokens.json is corrupt (parse error), superd refuses to start instead of wiping tokens — see FAQ — Corrupt tokens.json.

Managing Tokens (HTTP API)

Login / logout / status

curl -X POST http://127.0.0.1:9002/api/v1/auth/login \
  -H "Authorization: Bearer <token-or-auth_secret>"

curl -X POST http://127.0.0.1:9002/api/v1/auth/logout \
  -H "Authorization: Bearer <token-or-auth_secret>"

curl -H "Authorization: Bearer <token>" http://127.0.0.1:9002/api/v1/auth/status

List Tokens

Admins see all tokens. Viewer/Operator see only their own token metadata (no secret).

curl -H "Authorization: Bearer <token>" http://127.0.0.1:9002/api/v1/auth/tokens

Renew (rotate) a Token

Same id/name/role; old secret is invalidated immediately. Non-admins may renew only their own token.

curl -X POST -H "Authorization: Bearer <token>" \
  http://127.0.0.1:9002/api/v1/auth/tokens/<id>/renew

Revoke a Token

Admin only.

curl -X DELETE -H "Authorization: Bearer <admin-token>" \
  http://127.0.0.1:9002/api/v1/auth/tokens/<id>

Roles