Lost or compromised keys

Use this runbook when an agent's private key is lost, leaked, copied to the wrong place, or suspected of misuse. The goal is to stop the key's authority, give the agent a new key without changing its identity, and confirm that evidence signed earlier stays verifiable.

How keys relate to the agent

An agent's stable ID (agt_…) is separate from its credentials. Each credential has its own lifecycle row: kind (jwk, x509, spiffe, oidc), thumbprint, validity, status (active, rotating, revoked) and superseded_by. Grants, pending actions and the right to resume belong to the agent ID, not to a key. Revoking one key therefore does not lose any pending work.

1. Identify the credential

Console: Customer tenants → tenant → Agents → agent detail (/app/tenants/:tid/agents/:aid). The credentials list shows each key's ID (crd_…), thumbprint, kind, status and validity. If you only have a thumbprint, search for it in Control:

axiom_post /v1/orgs/$ORG/search '{"q":"<thumbprint>"}'

(The shell helpers axiom_post and axiom_get are defined in Runbooks.)

2. Revoke it

Console: Agent detail → the credential → Revoke, with a reason. API:

axiom_post /v1/agents/agt_01…/credentials/crd_01…/revoke '{"reason":"Key file exposed in CI logs"}'

Effects, in order:

1. The credential's status becomes revoked, with revoked_at and revoked_reason.
2. Every access token issued against that credential is revoked immediately. The next call made with such a token fails with 401 invalid_token (reason_code: credential_revoked), and the key can no longer obtain tokens (invalid_client).
3. Approved actions submitted under that credential fail their fresh authority check at resume and move to revoked (credential_revoked), even if the agent later resumes with a new key. Submit those intents again with new operation keys after re-keying.
4. For an x509 credential issued through the CA port, Axiom asks the CA to revoke the certificate by serial number. This is best effort: a CA outage does not block revocation in Axiom (which is what stops authority); the failure is logged for follow-up. In this preview the Sectigo SCM adapter runs in mock mode unless SCM credentials are configured, so check the CA separately.

If you need to stop all of the agent's keys, or you suspect the agent itself, suspend the agent instead (see Disabled agents). In an incident, a credential target also revokes tokens bound to that key while leaving the agent and its other keys alone.

3. Bind a new key with proof of possession

Generate a new key where the agent runs, then bind its public key. Binding always requires the new key to sign Axiom's single-use challenge. With the CLI:

axiom keygen --agent agt_01…                 # new private key on this machine (0600)
export AXIOM_SESSION_COOKIE='…'              # axiom_session cookie of a signed-in tenant admin
axiom agent bind agt_01…                     # challenge → sign with the key → bind

Or, from the console's agent detail page ("bind a key you hold"), copy the challenge payload and sign it with axiom agent sign-challenge '<payload JSON>' --agent agt_01…, then paste the printed proof back. Details are in Registering and admitting agents. Binding a key that is already bound is refused with 409 conflict; always generate a fresh key.

Binding a new key moves the agent's other active key credentials (jwk and x509) to rotating with a bounded overlap (rotation_overlap_seconds, default one day, at most seven). For a compromised key, revoke it first (step 2) so it gets no overlap window.

4. Resume pending work under the same agent ID

The agent runtime switches to the new key (AxiomAgent.rotateSigner(newSigner) in the SDK, or a new key_file for the CLI) and authenticates as the same agt_…. Its actions still in pending_approval or approved remain its own:

axiom status act_01…
axiom resume act_01…

Exception: actions submitted with the revoked credential are refused at resume (step 2). Actions submitted with a legitimately rotated (not revoked) key resume normally.

5. Confirm historical evidence still verifies

Revoking an agent key does not affect receipts: receipts are signed by Axiom's observation key and the provider's outcome key, and record the agent's credential thumbprint as a claim. Axiom's signing keys are kept in /.well-known/jwks.json after rotation (annotated axiom:status of active, retired or revoked) so old receipts keep verifying.

axiom receipt act_01… --out receipt.json
axiom verify receipt.json --issuer-jwks https://api.sectigoaxiom.com/.well-known/jwks.json

The report names the agent credential thumbprint each receipt was issued under. A receipt whose Axiom signer is now marked revoked in the fetched JWKS is reported as not valid. Verifying an old signature and establishing a credential's current status are separate questions: the receipt shows what was true at signing, the agent detail page shows the current status.

Checklist

• [ ] Credential revoked with a reason; tokens revoked.
• [ ] CA revocation confirmed for x509 credentials (or followed up).
• [ ] New key bound with proof of possession; other old keys rotating or revoked.
• [ ] Pending actions resumed or resubmitted; actions under the revoked key resubmitted with new keys.
• [ ] Audit events agent.credential_revoked and agent.credential_bound present in the SIEM.