> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, setup tokens, auth profiles, and gateway 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:

```json theme={null}
{
  "gateway": {
    "auth": {
      "enabled": true,
      "token": "your-secret-gateway-token"
    }
  }
}
```

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

### 2. API Provider Auth (Auth Profiles)

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

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

See [Auth Profiles](/models/auth-profiles) for details on managing multiple provider keys.

### 3. Channel Auth

Controls who can interact with the agent through each channel:

```json theme={null}
{
  "channels": {
    "telegram": {
      "allowedUsers": [123456789]
    },
    "discord": {
      "allowedGuilds": ["guild-id"]
    }
  }
}
```

## Auth Types

<Tabs>
  <Tab title="Setup Tokens">
    Generated from Anthropic Max subscriptions:

    ```bash theme={null}
    claude setup-token
    # Output: sk-ant-oat01-...
    ```

    * Bill against subscription weekly quota
    * Used for Max subscription accounts
    * No prompt caching support
  </Tab>

  <Tab title="API Keys">
    Standard per-token billing:

    ```
    sk-ant-api03-...
    ```

    * Bill per token used
    * Support prompt caching
    * Used for pay-as-you-go accounts
  </Tab>
</Tabs>

## 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

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

## Generating Auth Tokens

### Gateway Token

Generate a random token:

```bash theme={null}
openssl rand -hex 32
```

Add it to your config:

```json theme={null}
{
  "gateway": {
    "auth": {
      "token": "the-generated-token"
    }
  }
}
```

### Anthropic Setup Token

```bash theme={null}
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)