Authentication & API keys

AgentOS uses bearer token authentication. Every API request must include an Authorization header with an API key.

---

Key types

AgentOS has three key types:

Key prefix	Type	Scope
aos_agent_…	Agent key	One agent. Reports runs and events for that agent, and invokes it if it is hosted.
aos_ws_…	Workspace key	The whole workspace. Reports runs for any agent, invokes any hosted agent, and manages the workspace through the MCP server and the control plane.
aos_user_…	Personal key	You, in every workspace you belong to. Works only with the MCP server and the control plane.

Which key do I use?

You want to…	Use
Report runs from code that runs one agent	Agent key
Report runs or invoke agents from one service that handles several agents	Workspace key
Answer an agent's question from your own app	Workspace key
Connect an MCP client, or manage agents, alerts and schedules from code	Workspace key or personal key
Act as yourself, with your own role, in one or more workspaces	Personal key
Invite or remove members, or create a workspace	Personal key (owner or admin role)

What each key can do

• Agent keys are limited to their own agent. Using one on another agent returns 403 FORBIDDEN. The MCP server and the control plane reject agent keys with 403.
• Workspace keys act with admin-level access to their workspace, except that they cannot invite or remove members.
• Personal keys act with your own role in the workspace. Because one key covers every workspace you belong to, each call must name the workspace, by slug or ID. With the SDK, pass the workspace option or set AGENTOS_WORKSPACE. The ingest and invoke endpoints reject personal keys.

---

Generating a key

Every key has the form aos_<type>_ followed by 32 characters. The full key is shown once, when you generate it. AgentOS stores only a hash, so afterwards the dashboard shows just the key's prefix.

Agent key

Owners, admins and members can generate agent keys.

1. Go to Agents and open the agent.
2. Open the Keys tab. (The Integration tab can also generate one while you set up the SDK.)
3. Click Generate key.
4. Copy the key immediately.

Workspace key

Only owners and admins can generate workspace keys.

1. Go to Backoffice → API Keys.
2. Under Workspace SDK Keys, click New.
3. Name the key and click Generate key.
4. Copy the key immediately.

Personal key

Any signed-in user can generate a personal key for themselves.

1. Go to Backoffice → API Keys.
2. Under Your Personal SDK Keys, click New.
3. Name the key and click Generate key.
4. Copy the key immediately.

---

Using a key

Pass the key as a bearer token in the Authorization header on every request:

curl -X POST https://agentos-ai.dev/api/ingest/v1/run/start \
  -H "Authorization: Bearer aos_agent_..." \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "your-agent-id", "trigger_type": "sdk" }'

With the TypeScript SDK, pass it once when you create the client. The SDK adds the header to every request:

import { AgentOS } from "@agentos-sdk/core";

const client = new AgentOS({
  agentId: "your-agent-id",
  apiKey: "aos_agent_...",
});

Any option you leave out is read from the environment:

Variable	Option	Notes
AGENTOS_API_KEY	apiKey	Required.
AGENTOS_AGENT_ID	agentId	Default agent for runs and invokes.
AGENTOS_WORKSPACE	workspace	Workspace slug or ID. Needed with a personal key.
AGENTOS_BASE_URL	baseUrl	Defaults to https://agentos-ai.dev.

---

Authentication errors

HTTP	Code	Cause
401	UNAUTHENTICATED	Missing, malformed, revoked or expired key
403	FORBIDDEN	The key's type or scope does not allow this call
403	WORKSPACE_SUSPENDED	The workspace is suspended

---

Revoking a key

Find the key in Backoffice → API Keys (or on the agent's Keys tab) and click Revoke. The key is rejected from its next request onward.

---

Security best practices

• Store keys in environment variables, never in source code.
• Give agent code an agent key. If it leaks, only that agent is exposed.
• Rotate keys periodically, and always after a suspected exposure.
• Never log the full key value.

# .env
AGENTOS_API_KEY=aos_agent_...
AGENTOS_AGENT_ID=your-agent-id

const client = new AgentOS(); // reads AGENTOS_API_KEY and AGENTOS_AGENT_ID