---
title: "Admin Tunnel Keys Reset"
method: POST
path: "/admin/tunnel-keys/reset"
---

# Admin Tunnel Keys Reset

`POST /admin/tunnel-keys/reset`

## Request

- Base URL: `https://api.local-mcp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.local-mcp.com/admin/tunnel-keys/reset`
- Auth: none declared. Required headers: `x-admin-key`

Revoke the live device key of ONE machine (lmcp-api#69, section 7-A: a machine that lost
its key needs a person in the loop). The next enrol is a first enrol. Admin-key only.

lmcp-api#264: the reset also revokes the machine's live tokens that nobody can vouch for once
the key is gone. A token is VOUCHED FOR when the live key signed for it: it is bound to that
key in tunnel_key_tokens (bearer proof, signed approval, reissue, and their rotate / `sig`
successors). An unsigned-dialog approval never writes a binding, and while a key enrolled
after #261 is live, a token it has not proven is approved exactly that way (#263) — so anyone
who minted one for this machine_id could get it approved, and with the key gone R2 would let
that token enrol the next key first. So:
  - a key that routes only on its own tokens (routing_bound): every live token NOT bound to it
    is revoked;
  - a grandfathered key (routing_bound false, including its `sig` successors), whose
    machine-wide ratchet may have let unsigned approvals through: every live token neither
    bound to it nor approved before its `sig` chain began is revoked.
The owner's token approved through an unsigned dialog is therefore revoked too: confirm the
owner's token with them and name it in `keep_token_prefix` (its 12-character prefix, or the
whole token); it must match exactly one live token of the machine, or nothing changes (400).
A machine with no live key is left untouched. If the key itself is a squatter's, the tokens
it proved are the squatter's: keep the owner's by name, and revoke the rest by hand.

Consequence to know before using it (#91 review obs 1): this also DROPS the ratchet — the
machine becomes 'cannot sign yet' until it re-earns it, and the first enrol after a reset is
open to whoever holds a surviving token for that machine (exactly section 8-A's keyless
window). So reset a machine only when its owner is about to re-enrol, and watch
`key_mismatch_refused` in /admin/device-keys for a key that did not come from the owner.

## Headers

- `x-admin-key` string, required

## Request body

- TunnelKeyResetRequest
  - `machine_id` string
  - `keep_token_prefix` string

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/local-mcp/apis/lmcp-api.md) · [All operations](https://skmtc.dev/local-mcp/apis/lmcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/local-mcp/apis/lmcp-api/revisions/f1f1c502623a?raw)