Authentication

Overview

ArgentOS uses multiple layers of authentication to secure different parts of the system. Understanding how each layer works helps you configure a secure deployment.

Authentication Layers

1. Gateway Auth

Protects the WebSocket control plane from unauthorized access:

{
  "gateway": {
    "auth": {
      "enabled": true,
      "token": "your-secret-gateway-token"
    }
  }
}

Clients (dashboard, channels) must present this token when connecting. Without it, anyone with network access could control your agent.

2. API Provider Auth (Auth Profiles)

Authenticates with model providers (Anthropic, MiniMax, etc.):

~/.argentos/agents/main/agent/auth-profiles.json

See Auth Profiles for details on managing multiple provider keys.

3. Channel Auth

Controls who can interact with the agent through each channel:

{
  "channels": {
    "telegram": {
      "allowedUsers": [123456789]
    },
    "discord": {
      "allowedGuilds": ["guild-id"]
    }
  }
}

Auth Types

Setup Tokens

Generated from Anthropic Max subscriptions:

claude setup-token
# Output: sk-ant-oat01-...

• Bill against subscription weekly quota
• Used for Max subscription accounts
• No prompt caching support

API Keys

Standard per-token billing:

sk-ant-api03-...

• Bill per token used
• Support prompt caching
• Used for pay-as-you-go accounts

Auth Resolution Priority

When the agent makes an API call, credentials are resolved in this order:

1. Auth profiles (auth-profiles.json) -- checked first
2. Environment variables (ANTHROPIC_API_KEY, etc.) -- fallback

This means auth profiles always take precedence. If you have both configured, the auth profile wins.

Generating Auth Tokens

Gateway Token

Generate a random token:

openssl rand -hex 32

Add it to your config:

{
  "gateway": {
    "auth": {
      "token": "the-generated-token"
    }
  }
}

Anthropic Setup Token

claude setup-token

Follow the prompts to authenticate with your Anthropic account.

Security Recommendations

• Rotate tokens periodically (monthly recommended)
• Never commit auth-profiles.json to version control
• Use file permissions: chmod 600 auth-profiles.json
• Monitor usage through provider dashboards for unexpected activity
• Use separate profiles for different environments (dev/prod)