​
Overview

AgentOS supports bearer-token authentication to secure your instance. When a Security Key is configured, all API routes require an Authorization: Bearer <token> header for access. Without a key configured, authentication is disabled. Generate keys through the AgentOS UI, configure them on your server, and use them across development environments, CI/CD pipelines, and production services.

​
Generate a Security Key

From the AgentOS control plane, generate a security key or set your own.
You can also create your own security key and set it on the AgentOS UI.

​
Enable Authentication

Set the OS_SECURITY_KEY environment variable where your AgentOS server runs. When present, the server automatically enforces bearer authentication on all API routes.

​
macOS / Linux (bash or zsh)

export OS_SECURITY_KEY="OSK_...your_copied_key..."
uvicorn app:app --host 0.0.0.0 --port 8000

​
Docker Compose

services:
  agentos:
    image: your-org/agentos:latest
    environment:
      - OS_SECURITY_KEY=${OS_SECURITY_KEY}
    ports:
      - "8000:8000"
How it works: AgentOS reads OS_SECURITY_KEY into the AgentOS router’s internal authorization logic. If configured, requests without a valid Authorization: Bearer header return 401 Unauthorized.

​
Key Rotation

  1. In the UI, click the Rotate icon next to “Security Key” to generate a new value
  2. Update the server’s OS_SECURITY_KEY environment variable and reload/redeploy AgentOS
  3. Update all clients, workers, and CI/CD systems that call the AgentOS API

​
Security Best Practices

  • Environment Isolation: Use different keys per environment with least-privilege distribution
  • Code Safety: Never commit keys to version control or print them in logs
  • Regular Rotation: Automate key rotation on a schedule (quarterly recommended) and after any suspected exposure

​
Troubleshooting

  • 401 Unauthorized: Verify the header format is exactly Authorization: Bearer <key> and that the server has OS_SECURITY_KEY configured
  • Local vs Production: Confirm your local shell exported OS_SECURITY_KEY before starting the application
  • Post-Rotation Failures: Ensure all clients received the new key. Restart CI/CD runners that may cache environment variables
  • Connection Issues: Check that your AgentOS instance is running and accessible at the configured endpoint