# Key Rotation

> Rotate Thoth MCP Proxy fleet credentials with validation and revocation controls.

Source: https://docs.atensecurity.com/docs/operations/key-rotation

Use this guide to rotate fleet-scoped keys for Thoth MCP Proxy.

## Rotation workflow

1. Create a new fleet-scoped key in **Thoth -> Build -> API Keys -> Create New API Key**.
2. In the key modal, set:
   - `Scope` = `Fleet`
   - `Target` = the fleet ID you are rotating
   - `Permissions` = only what the fleet needs (`read`, `write`, `execute`)
   - If you need to create a new fleet first, set `Region` to the fleet's actual control-plane region (for many CorpSec fleets this is `us-east-1`; use `us-west-2` only if that fleet is actually west-managed)
3. Copy and securely store the new key immediately (shown once).
4. Update Jamf or Intune runtime configuration with the new key reference.
5. Force profile refresh for the target smart group.
6. Validate endpoint health and check-in continuity.
7. Revoke the old key after the validation window.

## Endpoint-scoped keys: machine identity guidance

When creating an `Endpoint` scoped key, use the endpoint's managed/immutable identity as the
primary scope target.

Recommended format:

- `endpoint_id`: lowercase letters/numbers/hyphens, e.g. `corpsec-mbp-naomi-nagata-01`
- optional hostname reference for inventory only, e.g. `mbp-naomi-nagata.local`

On macOS, get hostname values with:

```bash
hostname
scutil --get LocalHostName
scutil --get ComputerName
```

On Windows, get hostname values with:

```powershell
hostname
$env:COMPUTERNAME
[System.Net.Dns]::GetHostName()
```

Proxy identity resolution order is:

1. Managed override (`THOTH_INTUNE_DEVICE_ID` / `INTUNE_DEVICE_ID` / `THOTH_JAMF_COMPUTER_ID` / `JAMF_COMPUTER_ID`)
2. OS machine identity
3. Hostname fallback

If key context and runtime identity differ, enforcer currently allows execution for valid keys and emits warning logs. Treat those warnings as drift signals and realign endpoint identity mappings.

Optional API equivalent (same control-plane contract):

```bash
curl -X POST "https://<govapi-host>/<tenant-id>/thoth/api-keys" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fleet-rotation-2026-04",
    "scope_level": "fleet",
    "scope_target_id": "<fleet-id>",
    "permissions": ["read","write","execute"]
  }'
```

Optional authorization check before broad rollout:

```bash
curl -X POST "https://<govapi-host>/<tenant-id>/thoth/api-keys/<key-id>/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<plaintext-key>",
    "permission": "execute",
    "resource_type": "fleet",
    "resource_id": "<fleet-id>"
  }'
```

## Emergency revocation

1. Add compromised key IDs to `THOTH_REVOKED_API_KEY_IDS_FILE`.
2. Push updated profile and force endpoint check-in.
3. Validate revocation status.

```bash
thoth health --json
```

Expected posture fields:

- `api_key.key_id`
- `api_key.expired`
- `api_key.rotation_required`
- `api_key.revoked`

## Required controls

- Define the rotation window before rollout.
- Keep blast radius bounded to fleet scope.
- Prepare rollback configuration before key cutover.
- Capture timestamped evidence of key update and revocation.