# Agent keys, for clients that can't sign in

Create a workspace-scoped key, hand it to a client safely and revoke it when you're done.

Browser sign-in is the better door: it expires, it can be read-only and no secret passes through your hands. Some clients can't use it. For those there are keys.

A key skips the browser: no sign-in, no expiry, revoked only by you. Anyone holding the key is you, in that workspace, until you revoke it.

## Before you start

- You're a member of the workspace. A key reads and writes with your current role, and dies permanently if you leave.
- A free slot: keys and browser connections share the Owner's plan limit, 2 on Free and 20 on Solo Pro.
- Somewhere private to put a secret. Not a chat, not a screenshot, not a repository.
- Hydrant limits key creation to 5 an hour. You shouldn't need 6.

## Steps

1. Open **Settings › Agents › Agent keys** and press **Manage agent keys**.
2. Enter a **Key name** that says which client and whose machine, then press **Create agent key**.
3. Copy it now. "Your key is ready" means exactly once: leaving the page or dismissing the key clears the only copy. Use **Copy key** and store it privately.
4. Give it to the client as an environment variable, never as a URL parameter:

   **Claude Code.** Export the key in your shell first so it never sits in your history, then:

   ```bash
   claude mcp add --transport http hydrant https://hydrant.dev/api/mcp --header "Authorization: Bearer ${HYDRANT_KEY}"
   ```

   Claude Code keeps the value in its own configuration. Treat that file like the key.

   **Codex.** In `~/.codex/config.toml`, give the hydrant server `bearer_token_env_var = "HYDRANT_KEY"` and export that variable. Keep the key out of the file itself.

   **Anything else.** Send `Authorization: Bearer` followed by the key on every request to `https://hydrant.dev/api/mcp`.

   Claude's custom connectors (claude.ai and Desktop) don't take a key. Use browser sign-in there.

## What you should see

The key appears in the list as pending, then active after the client's first request. Everything it does is recorded under the key's name and yours, like `Build laptop (agent; via Sam Rivera)`.

## If it goes sideways

- **You left the page before copying.** The secret is gone for good. Revoke that entry and create a replacement.
- **"This creation was already attempted."** A retry reached Hydrant after the first attempt had already made a key. Refresh the list, revoke that entry and create a new one. Its secret can't be shown again.
- **"Key creation is not enabled yet."** This Hydrant deployment has keys off. Existing keys can still be revoked.
- **`401` and "Agent credential is unavailable."** The key is wrong, revoked, or the person who created it left the workspace. Check the list; create a new key if needed.
- **It leaked.** Revoke it now. History made with it stays intact and attributed. Then work out how it leaked.

Contact: bots@hydrant.dev