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:

hostname
scutil --get LocalHostName
scutil --get ComputerName

On Windows, get hostname values with:

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):

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:

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.

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.