Authentication

Every request to the HeroUI Agents API requires an Agent API key. Keys belong to one Agent, and a successful request can only return resources owned by that Agent.

Create and manage keys in the Agent API keys dashboard.

Authorization header

Use the HTTP Bearer scheme:

Authorization: Bearer he_...

For example:

curl "https://api.heroui.pro/v1/conversations?limit=20" \
  --header "Authorization: Bearer $HEROUI_AGENT_API_KEY" \
  --header "Accept: application/json"

Permissions

Each key has an explicit set of permissions:

Choose the smallest set that satisfies the integration. A reporting service that reads runs, for example, does not need auth_tokens:create, users:read, or conversations:read.

Keys created before permissions were introduced retain only auth_tokens:create. Legacy keys never gain access to users, conversations, or runs automatically; create a scoped replacement when you need public API access.

Authentication errors

• A missing, malformed, revoked, or unknown key returns 401 unauthorized.
• A valid key without the endpoint's required permission returns 403 insufficient_scope.

The error message identifies the missing permission. Do not retry either response without changing the key or its permissions.

Rotate a key

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.