Authenticate server-to-server requests with a scoped workspace API key.
The HeroUI Agents API accepts scoped workspace keys or resource-bound API tokens exchanged from an Agents MCP OAuth grant. The MCP handles that exchange automatically; its original access token is not accepted by REST. See Agents MCP authentication.
The existing browser-token endpoint retains its X-HeroUI-Agent-Key header and SDK contract. All management and monitoring operations use Bearer authentication. Pro personal and CI/CD tokens do not authenticate Agents.
Create and manage keys in the workspace API keys dashboard.
Use the HTTP Bearer scheme:
Authorization: Bearer he_...For example:
curl "https://api.heroui.pro/v1/agents/$HEROUI_AGENT_ID/conversations?limit=20" \
--header "Authorization: Bearer $HEROUI_AGENT_API_KEY" \
--header "Accept: application/json"Workspace API keys are server-side secrets. Never expose one in JavaScript shipped to a browser, a mobile application, logs, analytics, or support messages.
Each key has an explicit set of permissions:
| Permission | Dashboard label | Allows |
|---|---|---|
auth_tokens:create | Connect the Agent to your app | Allow people to use this Agent in your app. |
users:read | View users | See the people who have used this Agent. |
conversations:read | View conversations | See conversations and messages between people and this Agent. |
runs:read | View runs | View this Agent's run history, including status, latency, and tool activity. |
knowledge:read | View knowledge | List knowledge documents and inspect their extracted markdown. |
knowledge:write | Manage knowledge | Add, update, refresh, schedule, and delete knowledge documents. |
Choose the smallest set that satisfies the integration. A reporting service that reads runs, for example, does not need token creation or knowledge management access. A knowledge importer can use knowledge:write without permission to read conversations.
401 unauthorized.401 unauthorized response.403 insufficient_scope.The error message identifies the missing permission. Do not retry either response without changing the key or its permissions.
Create a replacement, deploy it to the server, verify traffic, and then revoke the old key. Revocation takes effect immediately. See API keys for the full rotation workflow.
Existing keys retain their original permissions. New management permissions are opt-in. OAuth consent also selects the accessible workspaces; membership and owner checks apply when an operation runs.
| Permission | Allows |
|---|---|
workspaces:read | List granted workspaces. |
usage:read | Read workspace usage, credits, and limits. |
agents:read | List Agents and inspect configuration. |
agents:write | Create Agents and update configuration. |
agents:archive | Archive or restore Agents; owner required. |
mcp_servers:read | Inspect third-party MCP connections. |
mcp_servers:write | Manage connections and discover tools; owner required. |
webhooks:read | Inspect webhook configuration and deliveries; owner required. |
webhooks:write | Configure webhooks and test or retry delivery; owner required. |
api_keys:create | Create a narrow integration key; owner plus auth_tokens:create required. |
GET /connection identifies the current credential and its effective permissions without requiring a discovery scope. It does not expose key secrets.