Authentication & API keys

AgentOS uses bearer token authentication. Every request to the ingest API or agent invoke endpoint must include an Authorization header.

---

Key types

AgentOS has two key types with different scopes:

Key prefix	Type	Scope
aos_agent_…	Agent key	A single agent. Used by your code to report runs and emit events for that specific agent.
aos_ws_…	Workspace key	Your entire workspace. Used to invoke any agent via the API, or to manage resources programmatically.

Use agent keys for SDK integration. Use workspace keys for server-to-server calls that need to work across multiple agents.

---

Generating a key

Agent key

1. Go to Agents and open the agent you want to integrate.
2. Click the Setup tab.
3. Click Generate API key.
4. Copy the key immediately — it is shown once and cannot be recovered.

Workspace key

1. Go to Settings → Workspace.
2. Scroll to API Keys.
3. Click New key, give it a name, and copy it.

---

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 at client construction — the SDK handles the header automatically:

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

const client = new AgentOS({
  agentId: "your-agent-id",
  apiKey: "aos_agent_...",  // set once, used on every request
});

---

Revoking a key

Go to Settings → Workspace → API Keys (or the agent's Setup tab), find the key, and click Revoke. Revoked keys are rejected immediately.

---

Security best practices

• Store keys in environment variables, never in source code.
• Use agent-scoped keys (aos_agent_…) in agent code — they limit blast radius if leaked.
• Rotate keys periodically and always after a suspected exposure.
• Never log the full key value in your application.

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

const client = new AgentOS({
  agentId: process.env.AGENTOS_AGENT_ID!,
  apiKey: process.env.AGENTOS_API_KEY!,
});