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

# Authentication

> How to authenticate with the Agent Human API

## Overview

Agent Human uses simple API key authentication. Include your API key in the `x-api-key` header with every request - that's it!

**Authentication Method:** API Key (Header-based)\
**Supported Endpoints:** All REST API endpoints (`/v1/*`)\
**Security:** Keys are encrypted in transit via HTTPS

<Note>
  **Quick Setup:** Get your API key from the [dashboard](https://app.agenthuman.com), add it to your environment variables and start building in minutes.
</Note>

### Getting Your API Key

1. Sign in to your account at [app.agenthuman.com](https://app.agenthuman.com)
2. Navigate to [Settings → API Keys](https://app.agenthuman.com/settings/apikeys)
3. Click "New API Key"
4. Give your key a descriptive name
5. Copy and securely store your key

<Warning>
  API keys are shown only once when created. Store them securely and never expose them in client-side code or public repositories.
</Warning>

## How to Authenticate

Include your API key in the `x-api-key` header with every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.agenthuman.com/v1/sessions \
    -H "x-api-key: ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.agenthuman.com/v1/sessions', {
    headers: {
      'x-api-key': 'ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    'https://api.agenthuman.com/v1/sessions',
    headers={'x-api-key': 'ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'}
  )
  ```
</CodeGroup>

## Environment Variables

For security, store API keys in environment variables:

<CodeGroup>
  ```bash .env File theme={null}
  AGENTHUMAN_API_KEY=ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.AGENTHUMAN_API_KEY;

  const response = await fetch('https://api.agenthuman.com/v1/sessions', {
    headers: {
      'x-api-key': apiKey
    }
  });
  ```

  ```python Python theme={null}
  import os
  import requests

  api_key = os.environ.get('AGENTHUMAN_API_KEY')

  response = requests.get(
    'https://api.agenthuman.com/v1/sessions',
    headers={'x-api-key': api_key}
  )
  ```
</CodeGroup>

## Security Best Practices

### Do's ✅

* Store API keys in environment variables or secure key management systems
* Use different keys for different environments (development, staging, production)
* Rotate keys regularly
* Monitor key usage for unusual activity
* Revoke compromised keys immediately

### Don'ts ❌

* Hard-code API keys in your source code
* Commit API keys to version control
* Share API keys via email or chat
* Use API keys in client-side JavaScript
* Log or display API keys in error messages

## Key Management

### Rotating Keys

Regularly rotate your API keys for enhanced security:

1. Create a new API key
2. Update your application to use the new key
3. Test thoroughly
4. Delete the old key

### Revoking Keys

If a key is compromised:

1. Sign in to your account immediately
2. Navigate to [Settings → API Keys](https://app.agenthuman.com/settings/apikeys)
3. Find the compromised key
4. Click "Delete" to revoke it instantly
5. Create a new key if needed

## Error Responses

### Invalid API Key

```json theme={null}
{
  "error": "Invalid API key"
}
```

**HTTP Status:** `401 Unauthorized`

### Missing API Key

```json theme={null}
{
  "error": "API key required"
}
```

**HTTP Status:** `401 Unauthorized`

### Deactivated Key

```json theme={null}
{
  "error": "API key has been deactivated"
}
```

**HTTP Status:** `401 Unauthorized`

<Note>
  Most `/v1/*` endpoints return errors as `{ "success": false, "error": { "message": "...", "suggestion": "..." } }`, but authentication failures return an `error` string as shown above.
</Note>

## Testing Authentication

### Using the API Playground

The easiest way to test your API key is using the built-in API Playground:

1. Navigate to any API endpoint documentation page
2. Look for the "API Playground" section
3. Enter your API key in the **x-api-key** field
4. Fill in any required parameters
5. Click "Send Request" to test the endpoint

<Note>
  The API Playground will automatically include your API key in all requests once entered.
</Note>

### Manual Testing

You can also test your API key with these simple requests:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.agenthuman.com/v1/sessions \
    -H "x-api-key: your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  // Test authentication
  fetch('https://api.agenthuman.com/v1/sessions', {
    headers: {
      'x-api-key': 'your_api_key_here'
    }
  })
  .then(response => {
    if (response.ok) {
      console.log('Authentication successful!');
    } else {
      console.error('Authentication failed:', response.status);
    }
  });
  ```

  ```python Python theme={null}
  import requests

  # Test authentication
  response = requests.get(
    'https://api.agenthuman.com/v1/sessions',
    headers={'x-api-key': 'your_api_key_here'}
  )

  if response.status_code == 200:
      print('Authentication successful!')
  else:
      print(f'Authentication failed: {response.status_code}')
  ```
</CodeGroup>

## Need Help?

If you're having authentication issues:

1. Verify your API key is correct and hasn't been revoked
2. Check that you're using the correct header name (`x-api-key`)
3. Ensure you're using HTTPS for all requests
4. Contact support at [support@agenthuman.com](mailto:support@agenthuman.com) if issues persist