Authentication

The Docent SDK supports API keys and two AWS workload-identity protocols. Use an organization service-account API key for most automation. In AWS-hosted environments, outbound OIDC avoids storing a Docent secret in the workload. Pass only one of api_key, aws_oidc_identity=True, or aws_federated_identity=True to a client.

Recommended setup

From your project directory, run the setup CLI and paste a key from Settings → API Keys when prompted:

uvx docent@latest setup

The prompt does not echo the key. Setup validates it before updating the global config at ~/.docent/docent.env. Use one of the manual options below for CI, secret managers, profile-formatted config, or project-specific overrides.

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

AWS outbound OIDC

AWS outbound OIDC is the preferred AWS authentication method. It mints a five-minute JWT for the Docent deployment origin and verifies the account’s issuer, the audience, the exact IAM role, and the token signature. Install the AWS extra:

pip install "docent[aws]"

An organization administrator must first connect the IAM role and its account-specific outbound OIDC issuer to a Docent service account. The workload role also needs sts:GetWebIdentityToken, restricted to the Docent API origin with sts:IdentityTokenAudience.

from docent import Docent

client = Docent(
    domain="docent.your-company.com",
    aws_oidc_identity=True,
)

The SDK uses the normal AWS credential chain. For a named local profile or an explicit regional STS endpoint:

client = Docent(
    domain="docent.your-company.com",
    aws_oidc_identity=True,
    aws_profile="sandbox",
    aws_region="us-east-1",
)

GetWebIdentityToken is unavailable on the global STS endpoint, so workloads must be able to reach a regional endpoint. The Docent API must be able to reach the issuer’s OIDC discovery and JWKS endpoints.

Legacy AWS signed-request authentication

Existing service-account bindings without an OIDC issuer can continue using the earlier audience-bound signed STS proof:

client = Docent(
    domain="docent.your-company.com",
    aws_federated_identity=True,
)

Use outbound OIDC for new bindings. Both AWS protocols stop authorizing new requests immediately when the service account is disabled or its IAM role is disconnected.

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 when AWS identity is not enabled	None
`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",
)

AWS authentication uses the same api_url, frontend_url, and domain resolution. The SDK derives the AWS token audience from the API URL’s origin. 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

Organizations

Agent Runs

DQL

Feedback & Labels

More

Legacy

Authentication

Recommended setup

API Key

1. Direct Parameter

2. Environment Variable

AWS outbound OIDC

Legacy AWS signed-request authentication

3. Config File

Configuration Priority

Environment Variables

Config File Format

Self-Hosted Instances

​Recommended setup

​API Key

​1. Direct Parameter

​2. Environment Variable

​AWS outbound OIDC

​Legacy AWS signed-request authentication

​3. Config File

​Configuration Priority

​Environment Variables

​Config File Format

​Self-Hosted Instances

Recommended setup

API Key

1. Direct Parameter

2. Environment Variable

AWS outbound OIDC

Legacy AWS signed-request authentication

3. Config File

Configuration Priority

Environment Variables

Config File Format

Self-Hosted Instances