> ## 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;
see the priority table below for the exact resolution order.

## 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

By default, create a global config file at `~/.docent/docent.env`:

```bash theme={null}
mkdir -p ~/.docent
cat <<'EOF' > ~/.docent/docent.env
DOCENT_API_KEY=your-api-key
DOCENT_COLLECTION_ID=my-default-collection
EOF
```

The default global config path is `~/.docent/docent.env`. The SDK also searches
for project-level `docent.env` files from the current working directory upward,
so local files can override the global default when present.
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 a discovered `docent.env` config file (project-level or `~/.docent/docent.env`).
</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>