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

# Authentication

> Authenticate your API requests

## API Keys

All Agent Diff API requests require authentication via an API key.

### Header Format

```bash theme={null}
X-API-Key: ad_live_sk_...
```

### Example Request

```bash theme={null}
curl -X GET https://api.agentdiff.dev/api/platform/health \
  -H "X-API-Key: ad_live_sk_3dqKGDx1QkqFw7RzPSfhrzMs..."
```

## Getting an API Key

<Tabs>
  <Tab title="Hosted">
    1. Sign up at [agentdiff.dev](https://agentdiff.dev)
    2. Go to your [dashboard](https://agentdiff.dev/dashboard)
    3. Navigate to **API Keys**
    4. Click **Create New Key**
    5. Copy and store your key securely

    <Warning>
      API keys are shown only once. Store them securely in environment variables.
    </Warning>
  </Tab>

  <Tab title="Self-Hosted">
    ```bash theme={null}
    cd ops
    make reissue-key
    ```

    This creates a development API key and prints it to console.

    For production, create keys directly in the database:

    ```sql theme={null}
    INSERT INTO api_keys (key_id, key_hash, user_id, created_at)
    VALUES ('abc123', 'hashed_secret', 'user-id', NOW());
    ```
  </Tab>
</Tabs>

## Using API Keys in SDKs

### Python

```python theme={null}
from agent_diff import AgentDiff, PythonExecutorProxy

# Via environment variable (recommended)
# export AGENT_DIFF_API_KEY="ad_live_sk_..."
# export AGENT_DIFF_BASE_URL="https://api.agentdiff.dev"
client = AgentDiff()
executor = PythonExecutorProxy(env.environmentId)  # Also uses env vars!

# Or explicit
client = AgentDiff(api_key="ad_live_sk_...")
```

### TypeScript

```typescript theme={null}
import { AgentDiff } from 'agent-diff';

// Via environment variable (recommended)
// export AGENT_DIFF_API_KEY="ad_live_sk_..."
const client = new AgentDiff();

// Or explicit
const client = new AgentDiff({ apiKey: 'ad_live_sk_...' });
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use environment variables">
    Never hardcode API keys in your source code:

    ```bash theme={null}
    # .env file (add to .gitignore!)
    AGENT_DIFF_API_KEY=ad_live_sk_...
    AGENT_DIFF_BASE_URL=https://api.agentdiff.dev
    ```

    ```python theme={null}
    from agent_diff import AgentDiff

    # SDK automatically reads from env vars
    client = AgentDiff()
    ```
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Create new keys periodically and delete old ones.
  </Accordion>

  <Accordion title="Use separate keys per environment">
    Use different API keys for development, staging, and production.
  </Accordion>

  <Accordion title="Monitor key usage">
    Review API usage in your dashboard to detect unauthorized access.
  </Accordion>
</AccordionGroup>

## Error Responses

### Missing API Key

```json theme={null}
{
  "ok": false,
  "error": "not_authed",
  "detail": "API key required"
}
```

### Invalid API Key

```json theme={null}
{
  "ok": false,
  "error": "not_authed",
  "detail": "Invalid API key"
}
```

### Expired API Key

```json theme={null}
{
  "ok": false,
  "error": "not_authed",
  "detail": "API key has expired"
}
```

## Rate Limiting

API keys have daily rate limits:

| Resource             | Daily Limit |
| -------------------- | ----------- |
| Environments created | 200         |
| API requests         | 2,000       |

When rate limited, you'll receive:

```json theme={null}
{
  "valid": false,
  "reason": "daily environment limit reached",
  "limit": 200,
  "current": 200
}
```

<Note>
  Need higher limits? Contact me at [hubert@uni.minerva.edu](mailto:hubert@uni.minerva.edu)
</Note>