Skip to content
Airdress Airdress Airdress Docs

Owner Token Recovery

This page is for administrators running their own airdress-operator host.

What the break-glass owner token is

Section titled “What the break-glass owner token is”

The routine way to authenticate as an operator’s owner is signing in with your identity provider (OIDC). The operator also supports an operator-issued opaque owner token — a bearer credential minted on the host itself. It exists as a break-glass fallback for when OIDC sign-in is unavailable: the identity provider is unreachable, or the operator’s OIDC configuration is broken.

The opaque token is not meant for day-to-day use. When it is in routine use, that is a signal something needs fixing.

The status-bar indicator in the VS Code extension

Section titled “The status-bar indicator in the VS Code extension”

When your active profile authenticates with an opaque owner token instead of an OIDC session, the Airdress VS Code extension shows a break-glass indicator in the status bar. The indicator is visibility only — it tells you a fallback credential is in use; it does not change any behavior.

If the indicator is showing persistently, treat it as a to-do: finish the recovery below by rebinding OIDC and retiring the opaque token. Once your profile is back on an OIDC session, the indicator clears.

The extension cannot mint a token — by design

Section titled “The extension cannot mint a token — by design”

The extension deliberately has no way to mint, print, or reveal an owner token, and this is verified by tests. Minting an owner token requires shell access on the operator host:

Terminal window
sudo airdress-operator owner-token print --confirm

That is the security property, not a missing feature: only someone with root on the box can produce an owner credential. If you are looking for a “generate token” button in the UI, stop looking and connect to the host instead.

Minting a new owner token invalidates the previous one — any session or tool still holding the old token is logged out on its next request. Sub-users are unaffected; they have their own credentials.

Recovery outline

Section titled “Recovery outline”
  1. Regain access to the operator host. Owner-token recovery always starts at a shell on the machine running airdress-operator.
  2. Mint a fresh token with sudo airdress-operator owner-token print --confirm. The --confirm flag is required; without it the command refuses to run, so you cannot invalidate your own session by accident.
  3. Rebind your OIDC identity once your identity provider is reachable again, so routine sign-in works without the opaque token.
  4. Retire the opaque token. Remove it from any tools or sessions that were using it. When nothing authenticates with it anymore, the extension’s break-glass indicator clears.
Section titled “Related”