# Owner Token Recovery

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

## 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

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

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:

```sh
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

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.

## Related

- [Sub-User Revocation](/operator/sub-user-revocation/) — removing a
  sub-user's access to an operator.