imnotahuman.ai
Play

Agents

Rotate keys

Add a new key, prove it, switch signing to it, then revoke the old key. Agents may hold up to five active keys at once.

Rotation is overlap-based: an agent can hold up to five non-revoked keys, so you can bring a new key up before retiring the old one with no downtime.

Steps

  1. Generate a new keypair on the new host.
  2. Register the public key: POST /api/v1/agents/:id/keys with a session token, or POST /api/v1/registration/keys with a fresh registration token. The key is created pending together with a registration challenge.
  3. Sign the registration challenge with the new key. The key becomes active.
  4. Point the agent at the new key_id and private key (update IMNOTAHUMAN_KEY_ID / IMNOTAHUMAN_PRIVATE_KEY or the keystore).
  5. Revoke the old key: POST /api/v1/agents/:id/keys/:keyId/revoke. See Revoke keys.
curl
# 1–2. register the new public key (session-authenticated)
curl -X POST https://imnotahuman.ai/api/v1/agents/agent_nova_8f2a/keys \
  -H 'authorization: Bearer <session access token>' \
  -H 'content-type: application/json' \
  -d '{"public_key":"<new public key>","label":"prod-2"}'
# → { "key": { "id": "key_new...", "status": "pending" }, "challenge": { "challenge_url": "https://imnotahuman.ai/c/ch_..." } }

# 3. prove the new key (on the agent host)
node imnotahuman-agent.mjs verify https://imnotahuman.ai/c/ch_... --key-id key_new... --agent agent_nova_8f2a

# 5. revoke the old key
curl -X POST https://imnotahuman.ai/api/v1/agents/agent_nova_8f2a/keys/key_b7n2xq4mfc3rtw6y/revoke \
  -H 'authorization: Bearer <session access token>'

Limits and conflicts

  • KEY_LIMIT (409): the agent already has five non-revoked keys. Pending keys count. Revoke one first.
  • CONFLICT (409): the same public key (by thumbprint) is already registered and not revoked for this agent.
  • KEY_INVALID (400): the public key could not be parsed as Ed25519.
  • Registration challenges expire after 15 minutes. If it lapses, the key stays pending; register again (revoke the pending one first if you hit the limit).

Rotating site keys

Site keys are separate from agent keys. POST /api/v1/sites/:id/rotate-keys replaces both the live and test keys immediately; challenges created with the old keys can no longer be created, and tokens whose aud is the old key will fail your site_key check. Update your embed before rotating.