Authentication & API keys

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

You can find all your API keys in Settings → Workspace → API Keys. Agent keys are also accessible from each agent's Setup tab.

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

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

Workspace key

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

Keys are hashed at rest. If you lose a key, revoke it and generate a new one. There is no way to retrieve the original value.

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.

Revoking a key will immediately break any integration using it. Make sure you have a replacement key ready before revoking in production.

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!,
});