Authentication

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

from docent import Docent

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

2. Environment Variable

export DOCENT_API_KEY="your-api-key"

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:

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:

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

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).

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:

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:

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:

export DOCENT_API_URL="https://api.my-docent.example.com"
export DOCENT_FRONTEND_URL="https://my-docent.example.com"

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

Getting Started

Collections

Agent Runs

DQL

Feedback & Labels

More

Legacy

Authentication

API Key

1. Direct Parameter

2. Environment Variable

3. Config File

Configuration Priority

Environment Variables

Config File Format

Self-Hosted Instances

​API Key

​1. Direct Parameter

​2. Environment Variable

​3. Config File

​Configuration Priority

​Environment Variables

​Config File Format

​Self-Hosted Instances

API Key

1. Direct Parameter

2. Environment Variable

3. Config File

Configuration Priority

Environment Variables

Config File Format

Self-Hosted Instances