Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

Operator-side surface for agent keys. Mint when bringing up a new agent, deprecate when rotating, revoke when retiring. All methods on this page live under App.agents — they require an app API key (alter_key_app_…). For the runtime use of these keys, see Agent runtime.

​
The key lifecycle

mint  →  active  →  deprecated  →  revoked
                       ↑↓
                  undeprecate
  • Active: the key works for Agent(api_key=...).
  • Deprecated: the key still works, but Alter sets X-Alter-Key-Deprecated: true on every response. Use this stage when rotating — allow the new key time to roll out before revoking the old one.
  • Revoked: the key fails immediately with KeyRevokedError and cannot be undeprecated.

​
Minting a key

result = await app.agents.mint_key(agent_id)
print(result.key_id, result.api_key)  # api_key plaintext shown once
The plaintext value is shown once in the response and never recoverable. Store it in the secret manager or env immediately. Mint a new one when the previous plaintext is lost.

​
Listing keys

result = await app.agents.list_keys(agent_id)
for key in result.items:
    print(key.key_id, key.status, key.created_at, key.last_used_at)
The list returns key metadata only — key_prefix, name, derived status, created_at, deprecated_at, revoked_at, last_used_at. The plaintext is never recoverable.

​
Rotating a key (deprecate → mint → revoke)

# 1. Mint the new key
new_key = await app.agents.mint_key(agent_id)

# 2. Deprecate the old key — still works, but flags the deprecated header on use
await app.agents.deprecate_key(agent_id, OLD_KEY_ID)

# 3. Roll out the new key to all instances of the agent.
#    Watch for the deprecated header on the old key in audit logs.

# 4. When no calls reference the old key anymore, revoke it
await app.agents.revoke_key(agent_id, OLD_KEY_ID)
Use undeprecate_key to restore a deprecated key to active status when a rotation is cancelled mid-flight.

​
Revoking a key

await app.agents.revoke_key(agent_id, key_id, force=True)
force=True is required when revoking the last active key — without it the call raises LastActiveKeyError to protect against accidentally locking out an agent. Use force=True when intentionally retiring the agent.

​
Common pitfalls

  • Keys are shown once. When the plaintext wasn’t captured, it cannot be recovered. Mint a new one and revoke the lost one.
  • last_used_at updates eventually. Avoid relying on it for live monitoring — it’s updated lazily on a cascade-isolated path. Use audit logs for real-time tracking.
  • LastActiveKeyError. Default-safe. Use force=True when actually retiring the agent.

​
See also