Authentication & keys
How Agent API keys work — Bearer auth, scopes, the GET /capabilities first call, zero-downtime rotation, instant revocation, and the audit log.
Every Agent API request is authenticated with an API key, sent as a Bearer token:
Authorization: Bearer bm_your_key_hereKeys start with the prefix bm_ and are shown once, at creation. Store yours somewhere safe — a secrets manager, not a chat message or a committed file. If you lose it, rotate to a new one.
API keys are currently available to a limited set of accounts while we finish rolling this out.
Scopes
Each key carries scopes that gate what it can do. Requests outside your key's scopes are rejected. Scopes include:
| Scope | Allows |
|---|---|
| Portfolio read | Reading your portfolios and holdings |
| Watchlist read/write | Reading and updating your watchlists |
| Market read | Reading market data |
| Reports read/write | Reading and working with reports |
A key only needs the scopes your integration actually uses — prefer narrow keys.
Your first call: GET /capabilities
Before anything else, call GET /capabilities. It returns what your key is allowed to do — its permissions, rate limits, and expiry — so you can build against reality instead of guessing:
curl https://blockmind.app/api/agent/capabilities \
-H "Authorization: Bearer bm_your_key_here"If a later request fails with a permission error, GET /capabilities is the quickest way to see what the key actually has.
Key lifecycle
Rotate: POST /keys/rotate
Rotation issues a replacement key that inherits the old key's permissions. The old key stays live during the cutover, so you can deploy the new key everywhere first and retire the old one without downtime.
Revoke: POST /keys/revoke
Revocation is the kill switch: the key stops working immediately. Use it the moment you suspect a key has leaked.
| Action | Endpoint | Effect |
|---|---|---|
| Rotate | POST /keys/rotate | New key with the same permissions; old key stays live for a zero-downtime cutover |
| Revoke | POST /keys/revoke | Key is dead instantly |
Audit log
Every call made with your key is recorded in an audit log. If something looks off — usage you don't recognize, calls at odd hours — revoke the key first and investigate second.
Security notes
- Keys grant access to your data. Treat them like passwords.
- The API is read-mostly and can never move funds — but a leaked key still exposes your portfolio and watchlist data, so rotate on any doubt.
- Never put a key in client-side code, a public repo, or a URL.
More on how BlockMind handles your data in Trust & security.