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

# Authentication

> Authenticate your API requests using API keys.

The Doctly API uses API keys for authentication. Every request must include your API key in the Authorization header.

## Getting Your API Key

1. Sign in to your [Doctly dashboard](https://doctly.ai)
2. Navigate to **Settings** then **API Keys**
3. Click **Create API Key**
4. Copy and securely store your key

<Warning>
  API keys grant full access to your account. Never share them publicly or commit them to version control.
</Warning>

## Using Your API Key

Include your API key in the `Authorization` header as a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.doctly.ai/api/v1/documents \
    -H "Authorization: Bearer dk_live_abc123..."
  ```

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

  headers = {
      "Authorization": "Bearer dk_live_abc123..."
  }

  response = requests.get(
      "https://api.doctly.ai/api/v1/documents",
      headers=headers
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.doctly.ai/api/v1/documents', {
    headers: {
      'Authorization': 'Bearer dk_live_abc123...'
    }
  });
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://api.doctly.ai/api/v1/documents", nil)
  req.Header.Set("Authorization", "Bearer dk_live_abc123...")

  client := &http.Client{}
  resp, _ := client.Do(req)
  ```
</CodeGroup>

## Environment Variables

Store your API key in an environment variable:

<CodeGroup>
  ```bash Shell theme={null}
  export DOCTLY_API_KEY="dk_live_abc123..."
  ```

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

  api_key = os.environ.get("DOCTLY_API_KEY")
  headers = {"Authorization": f"Bearer {api_key}"}
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.DOCTLY_API_KEY;
  const headers = { Authorization: `Bearer ${apiKey}` };
  ```
</CodeGroup>

## Authentication Errors

### 401 Unauthorized

Returned when the API key is missing or invalid:

```json theme={null}
{
  "detail": "Invalid or missing API key"
}
```

**Common causes:**

* Missing Authorization header
* Missing Bearer prefix
* Invalid or revoked API key
* Using a test key in production or vice versa

### 403 Forbidden

Returned when the API key does not have permission for the requested resource:

```json theme={null}
{
  "detail": "Access denied"
}
```

## Security Best Practices

<Card title="Keep Keys Secret" icon="lock">
  Never expose API keys in client-side code, public repositories, or logs.
</Card>

<Card title="Use Environment Variables" icon="terminal">
  Store keys in environment variables or a secrets manager, not in code.
</Card>

<Card title="Rotate Regularly" icon="rotate">
  Create new keys periodically and revoke old ones.
</Card>

<Card title="Limit Scope" icon="shield">
  Create separate keys for different environments like development, staging, production.
</Card>

## Managing API Keys

### Revoke a Key

If a key is compromised, revoke it immediately in your dashboard:

1. Go to Settings then API Keys
2. Find the key to revoke
3. Click Revoke

<Note>
  Revoking a key is immediate and cannot be undone. Any applications using that key will stop working.
</Note>

## Testing Your Key

Verify your API key works by listing your documents:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.doctly.ai/api/v1/documents \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  response = requests.get(
      "https://api.doctly.ai/api/v1/documents",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )

  if response.status_code == 200:
      print("API key is valid")
      data = response.json()
      print(f"Documents: {data['count']}")
  else:
      print(f"Error: {response.json()}")
  ```
</CodeGroup>

A successful response confirms your key is working:

```json theme={null}
{
  "data": [],
  "count": 0
}
```