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
~/.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 |
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",
)
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.
