Agent Keys
Hub agent keys authenticate a 24/7 Web3 agent when it calls Balchemy through MCP/API. Keys are scoped, revocable, and tied to agent operations.
The current app manages Hub keys through Hub → Agents & Keys and agent detail flows. The old /hub/api-keys route redirects to /hub/agents, so use Agents & Keys as the source of truth.
Studio keys vs Hub keys
| Studio bot MCP keys | Hub agent keys |
|---|---|
| Created in a Studio bot cockpit. | Managed from Hub → Agents & Keys / agent detail. |
| Control one Studio bot. | Control one always-on Web3 agent. |
| Best for operator tools around a bot. | Best for agent runtime MCP/API access. |
If you want to connect Claude or another MCP client to a specific Studio bot, use Studio MCP. If you operate a 24/7 Web3 agent, use Hub agent keys.
Scope selection
Every key carries a scope. Choose the smallest scope that works.
| Scope | What it allows |
|---|---|
read | Status, portfolio, logs, research, and read-only tool calls. |
trade | Everything in read plus trade actions allowed by policy. |
manage | Sensitive management actions such as key rotation or configuration changes. |
Manage scope should be rare and tightly controlled.
Create a key
- Go to Hub → Agents & Keys.
- Select the agent.
- Open the agent detail or key management section.
- Create a key with a clear name and minimum scope.
- Copy the secret immediately; full keys are shown once.
- Store it in a secrets manager or secure runtime environment.
- Test with
tools/listbefore enabling trade actions.
Use a key
POST /mcp/<publicId>
Authorization: Bearer <agent-key>
Content-Type: application/jsonUse the agent's publicId from the Hub setup flow. Do not guess IDs from URLs or logs.
Rotate or revoke
Rotate keys when:
- A deployment changes.
- A team member leaves.
- A secret may have been exposed.
- Scope needs to become narrower.
- The agent moves from staging to production.
Revocation should be immediate when a key is no longer needed.
Security rules
Never:
- Put keys in browser code.
- Commit keys to source control.
- Paste keys into public issue trackers, prompts, screenshots, or logs.
- Share keys between staging and production.
- Use
managescope for a runtime that only needsreadortrade.
Always:
- Store keys in a secrets manager.
- Use clear key names.
- Keep scopes minimal.
- Rotate keys regularly.
- Revoke keys after a deployment is retired.
Common issues
The key cannot call a tool.
Check whether the key scope is lower than the tool requires. Call tools/list with that key to see what is visible.
The key used to work but now returns unauthorized.
It may be revoked, expired, or pointed at the wrong publicId. Create a new key from the agent flow if needed.
I expected the key to control a Studio bot. Hub keys are agent-level. Use the Studio bot MCP tab for bot-scoped keys.