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

# Agent Therapy API Authentication and Key Management

> Agent Therapy authenticates every request via API keys passed in the Authorization header. Learn how to generate, scope, rotate, and revoke keys.

Agent Therapy authenticates your requests using API keys. Every request you send to the REST API must include your API key in the `Authorization` header using the Bearer scheme. Requests made without a valid key — or with a key that has been revoked — will receive a `401 Unauthorized` response.

```
Authorization: Bearer <your_api_key>
```

API keys are prefixed with `at_` so they are easy to identify if you ever need to audit your codebase or environment variables.

> [!WARNING]
>
> API keys are shown **only once** at the time of creation. Copy your key and store it somewhere secure immediately — it cannot be retrieved again. If you lose a key, you must rotate it.

## Getting Your API Key

**1. Log in to the dashboard**

Navigate to [app.agenttherapy.ai](https://app.agenttherapy.ai) and sign in with your account credentials.

**2. Open API Keys settings**

Click your avatar in the top-right corner, then select **Settings**. In the left sidebar, choose **API Keys**.

**3. Generate a new key**

Click **Generate New Key**. A modal will appear asking you to configure the key.

**4. Name your key and set its scope**

Give the key a descriptive name (for example, `production-monitoring-bot`) and select the appropriate scope. See [API Key Scopes](#api-key-scopes) below for guidance on choosing the right scope.

**5. Copy and store your key**

Your new API key is displayed once. Copy it now and store it in a secure secrets manager or environment variable. Once you close the modal, the key value cannot be shown again.

## Using Your API Key

Pass your API key as a Bearer token in the `Authorization` header on every request.

**curl:**

```bash theme={null}
curl https://api.agenttherapy.ai/v1/agents \
  -H "Authorization: Bearer at_your_key_here"
```

**Python (requests):**

```python theme={null}
import requests

API_KEY = "at_your_key_here"

response = requests.get(
    "https://api.agenttherapy.ai/v1/agents",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
agents = response.json()
```

**Python (agent-therapy-sdk):**

```python theme={null}
from agent_therapy import AgentTherapyClient

client = AgentTherapyClient(api_key="at_your_key_here")
agents = client.agents.list()
```

> [!NOTE]
>
> When using the SDK, you can also set the `AGENT_THERAPY_API_KEY` environment variable and omit the `api_key` argument entirely. The SDK will pick it up automatically.

## API Key Scopes

Every API key is assigned a scope that limits what it can do. Use the most restrictive scope that satisfies your use case.

| Scope | Permitted Operations | When to Use |
| - | - | - |
| `read` | All `GET` requests | Dashboards, monitoring, or read-only integrations |
| `write` | `GET`, `POST`, `PATCH`, and `DELETE` requests on agents, sessions, diagnostics, and interventions | Application backends that need to register agents and submit sessions |
| `admin` | All operations, including managing API keys and account settings | Internal tooling and automation that manages the platform itself |

> [!NOTE]
>
> Intervention endpoints require `write` scope. Creating, rotating, and revoking other API keys requires `admin` scope.

## Managing API Keys

You manage all of your API keys from the **Settings > API Keys** page in the dashboard.

**Listing keys:** All keys associated with your account are shown in a table with their name, scope, creation date, and last-used timestamp. The key value itself is never shown after creation.

**Rotating a key:** Click **Rotate** next to any key to instantly generate a replacement with the same name and scope. The old key is immediately invalidated. Update any services that used the old key before rotating to avoid downtime.

**Revoking a key:** Click **Revoke** to permanently deactivate a key. Revoked keys cannot be re-enabled; you must generate a new key if needed.

## Security Best Practices

> **Never commit keys to code**
>
> Treat API keys like passwords. Never hard-code them in source files or commit them to version control. Scan your repositories with a secrets detection tool to catch accidental exposure.

> **Use environment variables**
>
> Store your API key in an environment variable such as `AGENT_THERAPY_API_KEY` and read it at runtime. For production deployments, use a secrets manager like AWS Secrets Manager, HashiCorp Vault, or GCP Secret Manager.

> **Rotate keys regularly**
>
> Establish a rotation schedule — for example, every 90 days — and rotate keys immediately if you suspect any exposure. The rotation flow in the dashboard takes less than a minute.

> **Use minimal-scope keys**
>
> Issue separate keys for separate services, each with the narrowest scope needed. A read-only monitoring dashboard should never hold a key with `admin` scope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.