> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate the agent's authentication key

> Generate a new agent key, deploy it, and retire the old one with no observability gap.

Agent keys can be rotated through the console without an
observability gap. The cloud accepts both the new key and the
previous key for 24 hours, so the deployment can roll over without
strict synchronisation.

## Steps

**1. Generate a new key**

In the console, open **Agents**, select the agent, then
**Rotate key**. The cloud:

1. Generates a new key, stores a hash of it, and returns the
   plaintext once.
2. Retains the previous key's hash, so the previous key keeps
   working for 24 hours. To cut it off at once (for example after a
   leak), tick **Invalidate the old key immediately** when rotating.

Copy the new key.

You can also rotate through the API with
[`POST /agents/{id}/rotate-key`](https://docs.use.observer/api/agents/post-agents-by-id-rotate-key)
(scope `write:agents`). The response carries the new key once, with
the agent's environment variables already containing it. Add
`?target=` (`docker`, `compose`, `kubernetes`, `systemd`, `launchd` or
`binary`) to also get that install command with the key filled in, or
`?include=install` for all of them. Send
`{"invalidate_immediately": true}` to cut off the old key at once.

```bash theme={null}
curl -X POST "https://use.observer/api/v1/agents/$AGENT_ID/rotate-key?target=docker" \
  -H "Authorization: Bearer $OBSERVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invalidate_immediately": false}'
```

**2. Or deliver the key through a claim link (optional)**

When the key should not appear in the API response, for example
because the caller is an AI assistant or a CI job whose output is
logged, add `?delivery=claim`. The key is rotated the same way, grace
window included, but the response holds no key:

```json theme={null}
{
  "agent": { "id": "...", "name": "prod-eu", "...": "..." },
  "delivery": "claim",
  "claim_url": "https://use.observer/console/acme/agents/claim/akc_...",
  "claim_expires_at": "2026-10-20T12:15:00Z"
}
```

Open `claim_url` while signed in to the console as a member of the
organization and select **Reveal key** to see the new key and its install
command. The link works once and expires after 15 minutes. It also stops
working if the key is rotated again or a newer claim link is issued for
the same agent. Observer keeps the key only in encrypted form until it
is revealed.

`POST /agents?delivery=claim` creates an agent the same way.

**3. Deploy the new key**

Update the agent's `AGENT_KEY` environment variable to the new
value. The deployment path depends on your runtime:

* **Docker**: `docker run -e AGENT_KEY=<new>` and restart the
  container.
* **Kubernetes**: update the `observer-agent` Secret and roll
  the Deployment (`kubectl rollout restart deploy/observer-agent`).
* **systemd**: edit `/etc/observer-agent.env`, then
  `systemctl restart observer-agent`.
* **launchd (macOS)**: edit `AGENT_KEY` in
  `~/Library/LaunchAgents/use.observer.agent.plist`, then load it
  again (`launchctl bootout gui/$(id -u)/use.observer.agent`, then
  `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/use.observer.agent.plist`).

The agent reconnects with the new key on its next heartbeat.

**4. Confirm the rotation took effect**

Open the agent's dashboard. The *Cloud* panel reports a successful
heartbeat with the new key. The Agents page in the console shows
the agent as **Running**.

**5. Retire the old key**

The previous key keeps working for 24 hours, then becomes invalid
automatically. To end the grace period on an earlier rotation, rotate
again with **Invalidate the old key immediately** ticked and deploy
the newest key. Subsequent requests with the previous key are
rejected.

## What the cloud sees

* The cloud stores a hash of each key, never the plaintext.
* The cloud stores a hash of the new key and retains the previous
  key's hash for the grace window.
* A request with the new key succeeds. A request with the previous
  key succeeds only until the grace window ends.
* A lost key cannot be recovered. Rotate to issue a replacement.

> [!WARNING]
>
> **Rotate after every secret-handling incident**
>
> Treat agent keys with the same care as any service credential.
> Rotate when an environment file is shared, when a developer
> with access leaves, or when a host's image is exported. The
> grace window makes rotation cheap; do it often.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.