Scopes and Access Control

Scopes are the mechanism by which Balchemy controls what an external agent can do. Every MCP tool call is checked against the scope carried by the API key in the request. Understanding scopes helps you grant the right level of access to each agent and avoid both over-permissioning and under-permissioning.

What you'll learn

• What the three scope levels are and what each one grants
• The full capability matrix across read, trade, and manage
• How step-up authentication works for sensitive operations
• How to use the Scope Matrix and impact simulation tools
• Best practices for scope assignment

What scopes are

A scope is a permission level attached to an API key. When an agent sends a request to an MCP endpoint, Balchemy's ApiKeyScopeGuard checks the key's scope against the requiredScope declared on the tool being called. If the key's scope is insufficient, the request is rejected with a 403 Forbidden response.

Scopes are hierarchical and cumulative:

read ⊂ trade ⊂ manage

A trade key automatically has all read capabilities. A manage key automatically has all trade and read capabilities. You never need to assign multiple scopes to a single key — choose the highest scope the agent needs.

Quick start: check your current scope configuration

Navigate to /hub/scopes and select a bot from the dropdown. The scope matrix table loads immediately and shows all 13 capabilities with their scope requirements. Use the What Breaks? simulation panel on the right to preview what happens if a scope level is removed from a key.

The three scope levels

read — view-only access

The read scope gives an agent access to all observational capabilities. An agent with only read scope can monitor, analyze, and report but cannot modify anything.

Use read for:

• Monitoring agents that track portfolio performance and send alerts
• Analytics integrations that need trade history and position data
• Dashboard or reporting tools built on top of Balchemy data
• Testing and debugging agents during development before you need live trades

trade — execute operations

The trade scope adds the ability to submit and cancel orders, and to manage strategies. It includes everything in read plus active trading capabilities.

Use trade for:

• Autonomous trading agents that execute strategies
• Signal-following agents that translate research outputs into orders
• DCA or rebalancing agents that modify portfolio allocations
• Most production agents that interact with the trading engine

manage — administrative control

The manage scope adds the ability to configure the system itself — creating and revoking keys, changing bot settings, and deleting resources. It includes everything in trade and read.

Use manage for:

• Orchestration agents that spin up and configure other agents
• Deployment pipelines that rotate credentials automatically
• Admin interfaces that expose Balchemy configuration to operators

manage-scope operations require step-up authentication. See the Step-Up Authentication section below.

Full capability matrix

The table below shows exactly which capabilities are available at each scope level. The Step-up column indicates capabilities that require additional identity verification even when the key has manage scope.

The five step-up-required capabilities are exclusively destructive or credential-mutating operations. Requiring step-up for these operations prevents accidental or unauthorized changes even if a manage key is compromised.

Step-up authentication

Step-up is a short-lived token that authorizes a manage-scope action within a 5-minute window. It works like a one-time password layered on top of the API key scope.

Why step-up exists

A manage key has the ability to revoke other keys, change bot configuration, and delete resources. If a manage key were compromised, an attacker could do significant damage in a short time. Step-up means that even with a valid manage key, the attacker cannot execute the most dangerous operations without also compromising the operator's authenticator app.

How step-up works

1. The operator navigates to the agent detail page at /hub/agents/[agentId]
2. The agent must be claimed first (claim is required for step-up)
3. Click Issue Step-Up — this calls POST /api/nest/bots/:botId/mcp/step-up
4. The server validates the operator's identity and issues a short-lived step-up token
5. The token is displayed in the Control Plane panel on the agent detail page and expires in 5 minutes
6. Include the step-up token in the request for any step-up-required operation

Step-up for API key creation (manage scope)

When creating a manage-scoped API key through the Hub UI, the step-up flow is integrated directly into the Create Key dialog:

1. Select Manage scope and click Continue
2. Review the elevated access warning
3. Click Proceed to Verify
4. Enter the 6-digit code from your authenticator app (TOTP)
5. The server validates the code and issues a step-up token internally
6. The key is created immediately after validation

Step-up token TTL

Token expires in: 5 minutes

After expiry, you must issue a new step-up token. The 5-minute window is intentional — it is long enough to complete a sequence of manage-scope operations but short enough that a stolen token has limited value.

MCP scope filtering

Balchemy's MCP server exposes a different number of tools depending on the environment variable MCP_EXPOSE_GRANULAR_TOOLS:

Even with all 106 tools exposed, every tool call still goes through scope enforcement. An agent with only read scope cannot call a trade-required tool regardless of how many tools are visible in the tool list.

The 7 default tools cover the most common agent use cases: portfolio summary, market data, trade execution, position management, order status, wallet balance, and ask bot. If your agent needs granular control — individual token approvals, DCA leg configuration, or referral operations — request the full 106-tool exposure from the platform operator.

Scope assignment flow

New agents receive their initial scope during the discovery process. Hub uses an automatic onboarding profile that grants trade scope by default. You do not need to configure scope at onboarding time.

To upgrade scope after onboarding:

1. Claim the agent from the agent detail page (required before scope changes)
2. Issue a step-up token (required for manage scope)
3. Use the Enable Manage button in the Control Plane panel to toggle manage scope
4. The scope change takes effect immediately for new requests; existing tokens are not affected

To downgrade scope:

1. Claim the agent (if not already claimed)
2. Issue a step-up token
3. Use Disable Manage in the Control Plane panel

Scope changes apply to the persisted backend policy for the agent. All subsequently issued keys for that agent reflect the updated policy.

Upgrading from read to trade

If you started with a read-scoped key for testing and now need to execute trades, you have two options:

Option A — Create a new trade-scoped key

Navigate to /hub/api-keys, click Create API Key, select trade scope, and use the new key in your agent configuration. Revoke the read key if it is no longer needed.

Option B — The agent onboards with trade scope by default

New agent discoveries automatically receive trade profile scope. You only need to manually create read-only keys if you explicitly want the lower scope.

The Scope Matrix page

Navigate to /hub/scopes to access an interactive scope explorer with two panels.

Capability matrix table

The left panel shows all 13 capabilities in a three-column matrix. Each row shows which scopes grant that capability. Rows with step-up requirements have a teal left border and a "Step-up" badge next to the capability name.

Click any column header (read / trade / manage) to highlight the affected rows. This helps you quickly see what capabilities would be lost if a key's scope were reduced.

What Breaks simulation panel

The right panel is a scope impact simulator. Select a scope level to see which capabilities would be affected if that scope were removed from a key. Each capability shows a plain-English explanation of what the agent can no longer do.

Simulated results for each scope:

Use this tool to understand the blast radius before removing a scope from a production key.

Best practices

Use the narrowest scope that works. A read key cannot accidentally execute a trade. A trade key cannot accidentally delete a bot. Assign the minimum scope needed and upgrade only when you have a concrete reason.

Separate keys by concern. If you have a monitoring agent and a trading agent pointing at the same bot, give them separate keys with separate scopes. This makes it easy to revoke the trading agent without affecting monitoring.

Name keys for traceability. Use names like "Arbitrage bot — prod — v3 — 2026-04" that tell you the agent, environment, version, and rotation date. This makes auditing straightforward when you are managing dozens of keys.

Rotate before expiry. Keys expire after 90 days by default. Set a reminder to rotate 2 weeks before expiry to avoid disruption. Create the new key, test it, then revoke the old one.

Test with read first. When integrating a new agent, start with a read-scoped key. Verify the agent can connect, list tools, and read data before upgrading to trade scope for live operations.

Monitor anomalies. The Hub dashboard shows error counts in the last 24 hours. An unexpected spike may indicate a compromised key. Investigate and rotate keys immediately if you see unexplained scope violations in the logs.

Configuration reference

Error handling

Related pages

• Hub Overview
• API Keys
• MCP Integration
• API Endpoints