Skip to Content
AgentKey Rotation

Agent Key Rotation

The agent proves its identity to the gateway with an Ed25519 key pair: the agent holds the private key, the gateway holds the public key. Rotate the pair on a schedule, when you move a customer to a new gateway, or immediately if the private key may have leaked.

Steps

  1. Generate a new key pair:

    ./onprest-gateway create-agent-secret

  2. Put the new public key in the gateway environment:

    GATEWAY_AGENT_PUBLIC_KEY=new-base64url-ed25519-public-key

  3. Put the new private key in the agent configuration, inline or in its key file:

    gateway:
  agent_private_key_file: ./secrets/agent.key

  4. In one maintenance window, restart the gateway, then restart the agent.

  5. Check that /healthz reports agent_connected: true, and call one capability through REST and MCP.

After the restart, the old private key can no longer connect, and the gateway loads a fresh capability contract from the agent. API keys are unaffected.

If the key may have leaked

The gateway accepts only one agent connection at a time, so a second agent using a stolen key cannot silently replace a connected one. Rotate the key and restart both sides anyway, so the connected agent is known to be yours. See Security for how the connection is protected.

Local LogsSecurity