# Sub-User Revocation

This page is for administrators running their own `airdress-operator` host.
Revocation is owner-only: only the operator's owner can revoke a sub-user.

## When to revoke

- **The sub-user is leaving** the household or operator. Revoke at the
  time of departure to close the credential window.
- **Their token is suspected leaked.** Treat it as a compromise: revoke
  immediately, then create a fresh sub-user. The same display name becomes
  available again as soon as the old principal is revoked.
- **Inactivity cleanup.** Revoking sub-users who have not signed in for a
  long time (for example, 90 days) is administrative hygiene — a smaller
  set of active principals is easier to audit.
- **Decommissioning the operator.** Revoke all sub-users before tearing
  the host down.

Do **not** revoke as a workaround for a bug. Revocation does not destroy
the sub-user's conversations, but it does cut off their access to them —
and re-adding the person later creates a *new* principal that cannot reach
the old history.

## Two ways to revoke

**CLI, on the operator host:**

```sh
# List active sub-users, then revoke by id.
sudo airdress-operator sub-users list
sudo airdress-operator sub-users revoke <id>
```

The CLI reports `revoked`, `no-op (already revoked)`, or `not found`.
Revocation is idempotent — running it twice is safe.

**VS Code extension — Principals view:**

The extension offers the same operation from its Principals view,
owner-only. It performs the identical revocation as the CLI — one
operation, two surfaces. Guard rails in the IDE flow:

- **Type-to-confirm**: the dialog requires typing the principal's label
  back before the revoke fires; there is no OK-only path.
- The extension confirms the revocation call succeeded — run the
  verification below yourself to confirm the downstream effects.

## What revocation does

- **Immediately invalidates the sub-user's credential.** The very next
  request bearing their token is rejected with `401 Unauthorized`.
- Marks the principal as revoked; it no longer appears in the active
  sub-user list.
- Frees the display name for reuse by a new sub-user.

## What revocation does NOT do

- **It does not delete the sub-user's conversations or messages.** Their
  message history is retained on the operator according to your
  operator's data-retention rules. Revocation removes access, not data —
  if you need the data erased as well (for example, on request from the
  departing person), that is a separate, deliberate deletion step under
  your retention policy.
- **It does not affect any other user.** The owner and all other
  sub-users keep working unchanged.
- **It is not reversible into the same account.** There is no
  "reactivate". If the person comes back, you create a new sub-user; the
  old conversations remain inaccessible to them.

## Verify after revoking

1. The revoked sub-user's requests fail: any request made with their
   credential now returns `401 Unauthorized`.
2. The active sub-user list (CLI `sub-users list` or the extension's
   Principals view) no longer shows them.

If a revoked sub-user's credential still works after revocation, restart
the operator service and check that exactly one operator process is
running — then revoke again.

## Related

- [Owner Token Recovery](/operator/owner-token-recovery/) — the owner's
  break-glass credential and how to retire it.