Authentication

Authenticate the Docent SDK with API keys or AWS workload identity

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.