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

# Authentication

> Configure API keys and connection settings for the Docent SDK

The Docent SDK authenticates via API keys. You can provide your key in several ways,
listed here in order of precedence.

## API Key

### 1. Direct Parameter

```python theme={null}
from docent import Docent

client = Docent(api_key="your-api-key")
```

### 2. Environment Variable

```bash theme={null}
export DOCENT_API_KEY="your-api-key"
```

```python theme={null}
from docent import Docent

client = Docent()  # Reads DOCENT_API_KEY from environment
```

### 3. Config File

Create a `docent.env` file in your project directory:

```bash theme={null}
DOCENT_API_KEY=your-api-key
DOCENT_COLLECTION_ID=my-default-collection
```

The SDK searches for `docent.env` starting from the current working directory and traversing up
the directory tree. You can also specify an explicit path:

```python theme={null}
client = Docent(config_file="/path/to/my-config.env")
```

## Configuration Priority

The SDK resolves each setting using a priority order. The exact order varies slightly
by setting:

| Setting                    | Priority (highest to lowest)                                                        |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `api_key`                  | Direct parameter → config file → `DOCENT_API_KEY` env var                           |
| `api_url` / `frontend_url` | Direct parameter → `DOCENT_API_URL` / `DOCENT_FRONTEND_URL` env var → config file   |
| `domain`                   | Direct parameter → `DOCENT_DOMAIN` env var → config file → `"docent.transluce.org"` |
| `collection_id`            | Direct parameter → config file                                                      |

<Note>
  `collection_id` is not read from environment variables — set it via a direct parameter
  or in your `docent.env` config file.
</Note>

## Environment Variables

| Variable              | Description                | Default                |
| --------------------- | -------------------------- | ---------------------- |
| `DOCENT_API_KEY`      | API key for authentication | *Required*             |
| `DOCENT_API_URL`      | Direct API server URL      | Derived from domain    |
| `DOCENT_FRONTEND_URL` | Direct frontend URL        | Derived from domain    |
| `DOCENT_DOMAIN`       | Docent instance domain     | `docent.transluce.org` |

## Config File Format

The config file uses dotenv format. Supported keys:

```bash theme={null}
DOCENT_API_KEY=your-api-key
DOCENT_API_URL=https://api.docent.transluce.org
DOCENT_FRONTEND_URL=https://docent.transluce.org
DOCENT_DOMAIN=docent.transluce.org
DOCENT_COLLECTION_ID=my-collection
```

## Self-Hosted Instances

For self-hosted Docent instances, set both the API and frontend URLs:

```python theme={null}
client = Docent(
    api_key="your-api-key",
    api_url="https://api.my-docent.example.com",
    frontend_url="https://my-docent.example.com",
)
```

Or via environment variables:

```bash theme={null}
export DOCENT_API_URL="https://api.my-docent.example.com"
export DOCENT_FRONTEND_URL="https://my-docent.example.com"
```

<Warning>
  Local domains (`localhost`, `127.0.0.1`) require explicit `api_url` and `frontend_url`.
  The SDK cannot derive URLs from local domains automatically.
</Warning>