Create, scope, and rotate workspace-wide keys used by your Agent integrations.
An API key authenticates your server, not your visitors. Each key can target every current and future active Agent in its workspace, subject to the permissions you assign. The key itself never leaves your infrastructure and the browser never holds a long-lived credential.
Keys are managed per workspace in the dashboard. Only the workspace owner can view, create, copy, rename, or revoke keys.
Names are how you tell keys apart when it is time to rotate one. production-web and staging are useful; key 1 is not.
Select only what this server needs. The embed token endpoint needs auth_tokens:create; data integrations need the matching users:read, conversations:read, or runs:read permission.
Copy the key into your secret manager. Active keys can also be copied later from the key table; revoked keys cannot be retrieved.
HEROUI_AGENT_API_KEY=he_...
HEROUI_AGENT_ID=your_agent_idSend a message from the embed. If your endpoint can mint a token, the conversation connects. A rejected key surfaces as an authentication failure rather than a silent empty response.
Never prefix the key with NEXT_PUBLIC_ or reference it in client code. Any variable a bundler
can see ends up in your JavaScript, and a leaked key can exercise every permission assigned to it.
| Permission | Dashboard label | Allows |
|---|---|---|
auth_tokens:create | Connect Agents to your app | Mint browser tokens for Agents in this workspace. |
users:read | View users | See people who have used Agents in this workspace. |
conversations:read | View conversations | See conversations and messages across Agents in this workspace. |
runs:read | View runs | View run history, latency, and tool activity across this workspace. |
knowledge:read | View knowledge | Read knowledge documents for Agents in this workspace. |
knowledge:write | Manage knowledge | Add, update, refresh, schedule, and delete knowledge documents. |
Use separate keys when services have different responsibilities. A backend that only exports run metrics, for example, needs runs:read but does not need access to users, conversations, or token minting.
The Agent is selected by the request path, for example /v1/agents/{agentId}/runs. A key cannot
target an Agent from another workspace.
Minting a browser token requires auth_tokens:create and must happen inside your own server route:
import {createAuthToken} from "@heroui/agent/server";
export async function POST(request: Request) {
const {anonymousId, agentId} = await request.json();
if (agentId !== process.env.HEROUI_AGENT_ID) {
return Response.json({error: "Invalid agent"}, {status: 400});
}
return Response.json(
await createAuthToken({
apiKey: process.env.HEROUI_AGENT_API_KEY!,
anonymousId,
identity: {id: anonymousId, type: "anonymous"},
agentId,
}),
{headers: {"Cache-Control": "no-store"}},
);
}See the Quickstart for the full setup and Identifying users for connecting tokens to signed-in people.
To query users, conversations, or runs from a server, see the HTTP API authentication guide.
The table shows each key's name, masked token, status, creator, and creation date. The full secret is encrypted at rest; only its prefix and last four characters appear until someone selects Copy.
| Action | Who can use it | Effect |
|---|---|---|
| Copy | The workspace owner | Decrypts and copies an active, retrievable key |
| Rename | The workspace owner | Changes the label only. The key keeps working |
| Delete | The workspace owner | Revokes the key. Requires typing the key name to confirm |
Revoking is immediate and cannot be undone. Any server still presenting a revoked key can no longer mint tokens or call the public API, and existing sessions are rejected on their next authenticated request across every Agent in the workspace.
Because a workspace can hold several active keys, rotation does not need downtime:
Rotate when someone with access leaves, when a key may have been exposed, or on whatever schedule your security policy sets.
Use separate keys and Agents for staging. Workspace-wide authorization does not merge their data; every public API request still names exactly one Agent.
Authentication fails after a deploy. Confirm the environment variable is present in the deployed environment, not only locally, and that the key has not been revoked.
A public API request returns 403 insufficient_scope. The key is valid but does not have the permission required by that endpoint. Create a replacement with the minimum required read permission.
Tokens are minted but the Agent is rejected. Confirm the agentId belongs to the same workspace as the key and that the Agent is active.
The key leaked. Revoke it immediately and create a replacement. Revocation takes effect at once; there is no need to wait for a deploy to finish first.