Configuration Guide

Last updated: July 21, 2026 Document type: Living guide

This guide explains how to configure britecore_sdk for your environment.

Minimum supported Python version: 3.11.

Overview

Configuration uses Dynaconf, a hierarchical settings manager that supports:

TOML files (primary)
Environment variables
Default values
Per-site overrides

Config Files

Canonical precedence table

Configuration is layered (lowest to highest priority):

Priority	Location	File(s)
1 (lowest)	SDK package defaults	`src/britecore_sdk/settings/settings.toml`, `src/britecore_sdk/settings/.secrets.toml`
2	User-level config	`~/.britecore/settings.toml`, `~/.britecore/.secrets.toml`
3	Project-local config	`./britecore.toml`, `./.britecore_secrets.toml`
4	Explicit file override	Path from `BRITECORE_SDK_SETTINGS_FILE`
5 (highest)	Environment variables	`BRITECORE_SDK_*`

Environment variables override all file-based values.

SDK package default files (mainly for source clones)

src/britecore_sdk/settings/
|-- sample/
|   |-- settings.toml  # Sample/template for public settings (tracked in git)
|   `-- .secrets.toml  # Sample/template for secrets (tracked in git, no real values)
|-- settings.toml      # Your public settings (tracked in git)
|-- .secrets.toml      # Your secrets (gitignored — never commit)
`-- config.py          # Dynaconf loader

Tip: For pip-installed usage, prefer user-level files (~/.britecore/...) or project-local files (./britecore.toml, ./.britecore_secrets.toml) instead of editing files under src/.

`settings.toml` (Public)

Contains default non-secret runtime settings (no credentials):

# Default runtime configuration (applies to all sites unless overridden)
[default]
web_timeout = 30        # API request timeout in seconds
web_retry = 10          # Number of retries for API requests
web_timeout_long = 60   # Long-running API request timeout in seconds

# Optionally set target_site here to avoid passing it in code or as an env var.
# target_site = "example_site"

# Site section definitions (no base_url or credentials — those go in .secrets.toml)
[example_site]
# Leave empty or add only non-sensitive configuration

[example_site_test]
# Leave empty or add only non-sensitive configuration

When to edit:

Add new site section headers (credentials go in .secrets.toml)
Override default API request settings (web_timeout, web_retry, web_timeout_long)
Set target_site under [default] to avoid passing it in code or as an environment variable

Never commit:

Any base_url, API keys, client IDs, client secrets, or credentials

`.secrets.toml` (Private)

Contains all sensitive credentials and site configuration. This file is gitignored.

# Default credentials template
[default]
base_url = ""
client_id = ""
client_secret = ""
api_key = ""

# Example: Site-specific credentials
[example_site]
base_url = "https://api.example.com"
client_id = "your_real_client_id"
client_secret = "your_real_client_secret"

[example_site_test]
base_url = "https://api-test.example.com"
api_key = "your_real_api_key"

How to create (source clone workflow):

Copy src/britecore_sdk/settings/sample/.secrets.toml to src/britecore_sdk/settings/.secrets.toml
Replace placeholder values with your real base_url and credentials for each site
Never commit .secrets.toml (it’s already gitignored)

File format:

All site credentials and base URLs go here
Values in .secrets.toml override settings.toml
All sections are optional

Loading Configuration

Automatic (Recommended)

# Recommended: Use the lazy-initialized client (auto-loads config on first use)
from britecore_sdk.api.api_calls import get_api_client

client = get_api_client()

What happens:

target_site selects the site section (for example [example_site])
Dynaconf resolves layered files (SDK defaults, user-level, project-local, explicit file)
BRITECORE_SDK_* environment variables override file values

Via `get_api_client()` (Lazy, Recommended)

from britecore_sdk.api.api_calls import get_api_client

# Lazy initialization -- config is loaded on first use
client = get_api_client()

Requires target_site to be set in settings.toml, as an environment variable, or passed explicitly to init_api_client() before calling get_api_client().

Environment Variables

You can set target_site and override config values with environment variables:

# Set the active site (alternative: set target_site in settings.toml [default])
$env:target_site = "example_site"

# Override a specific setting (BRITECORE_SDK_* env vars take precedence over .secrets.toml)
$env:BRITECORE_SDK_BASE_URL = "custom.britecore.com"

# System selection (for regex maps, if applicable)
$env:system = "example_site"

target_site resolution order (first non-empty value wins):

Explicit argument passed to init_api_client(target_site=...)
target_site key in settings.toml under [default]
target_site environment variable

Role of target_site: target_site selects which section of .secrets.toml (and settings.toml) is used to load credentials. When all required credentials are supplied via BRITECORE_SDK_* environment variables, the specific target_site value does not affect which credentials are loaded — env vars take precedence over TOML values regardless of the section name. However, target_site is still required for client initialization. If any required credential is missing from env vars, the client will fall back to the .secrets.toml section matching the target_site value, so the name must correspond to a real section in that case.

Priority order for other config values (highest to lowest):

Environment variables (for example BRITECORE_SDK_*)
Explicit file path from BRITECORE_SDK_SETTINGS_FILE
Project-local files (./britecore.toml, ./.britecore_secrets.toml)
User-level files (~/.britecore/settings.toml, ~/.britecore/.secrets.toml)
SDK package defaults (src/britecore_sdk/settings/settings.toml, src/britecore_sdk/settings/.secrets.toml)

Required Keys by Auth Mode

API Key Auth

Required keys:

base_url – API base URL
api_key – API key value

Optional:

client_id (leave blank to skip OAuth)
client_secret (leave blank to skip OAuth)

OAuth Auth

Required keys:

base_url – API base URL
client_id – OAuth client ID
client_secret – OAuth client secret

Optional:

api_key (will be ignored if client_id + client_secret are set)

Auth mode selection:

if client_id and client_secret:
    # Use OAuth
else:
    # Use API key

Optional Utility Keys

These keys are optional and only used when importing/calling the related utilities.

Validation

When you call client.init_client(), Dynaconf validates required keys. This is only needed for advanced/manual scenarios. For most use cases, prefer get_api_client().

You can also validate all configured site sections directly:

python -m britecore_sdk.utils.check_site_configs

python -m britecore_sdk.utils.check_site_configs

Then run an end-to-end readiness check for a specific site:

python -m britecore_sdk.utils.healthcheck --site example_site

python -m britecore_sdk.utils.healthcheck --site example_site

check_site_configs validates each site section in src/britecore_sdk/settings/.secrets.toml using this rule:

base_url is required
auth must be either:
- OAuth pair (client_id and client_secret together), or
- API key (api_key)

The utility also warns when sensitive keys (api_key, client_id, client_secret) are present in settings.toml.

Common errors:

Error	Cause	Fix
`BritecoreKeyError`	Missing `base_url`	Add `base_url` to `.secrets.toml` site section or set `BRITECORE_SDK_BASE_URL`
`BritecoreKeyError`	Missing `client_id`/`client_secret`	Add both for OAuth, or add `api_key` for API key auth
`BritecoreKeyError`	Missing `api_key`	Add `api_key` to `.secrets.toml`
Config not loading	`target_site` not set	Set `target_site` in `settings.toml` `[default]`, set `$env:target_site`, or pass to `init_api_client(target_site="site_name")`
`INCORRECT` in `check_site_configs` output	Missing required site keys in `.secrets.toml`	Add missing keys shown in `Missing Keys` column

Per-Environment Setup

Development

# Set environment for local testing
$env:target_site = "example_site_test"

# Create .secrets.toml with test credentials
# [example_site_test]
# api_key = "your_test_key"

CI/CD Pipelines

Store credentials as GitHub repository secrets:

Go to Settings -> Secrets and variables -> Actions
Create secrets:
- BRITECORE_CLIENT_ID
- BRITECORE_CLIENT_SECRET
- BRITECORE_API_KEY
- BRITECORE_BASE_URL
- (any others needed)
Reference in workflow:

env:
  BRITECORE_SDK_BASE_URL: ${{ secrets.BRITECORE_BASE_URL }}
  BRITECORE_SDK_API_KEY: ${{ secrets.BRITECORE_API_KEY }}
  target_site: example_site_test  # required; selects .secrets.toml section (any name works when all creds are in env vars)

Production

Use environment variables or a secrets management system (e.g., AWS Secrets Manager, HashiCorp Vault):

# Before app startup
$env:BRITECORE_SDK_BASE_URL = "prod.britecore.com"
$env:BRITECORE_SDK_CLIENT_ID = "prod_client_id"
$env:BRITECORE_SDK_CLIENT_SECRET = "prod_client_secret"
$env:target_site = "example_site"  # required; value only matters if .secrets.toml is also used

# Then start your application
python app.py

API-only deployment checklist

Install base package only (pip install -e .); do not install optional extras unless needed.
Set target_site to a configured site section in settings.toml/.secrets.toml, or any non-empty string when all credentials are supplied via BRITECORE_SDK_* env vars.
Set BRITECORE_SDK_BASE_URL for the target BriteCore instance.
Choose one auth mode: either set BRITECORE_SDK_API_KEY, or set both BRITECORE_SDK_CLIENT_ID and BRITECORE_SDK_CLIENT_SECRET.
Store production secrets in a secrets manager (Vault, AWS Secrets Manager, etc.), not in committed files.
Verify startup with a minimal init check (get_api_client()) before serving traffic. Use BritecoreAPIClient(...).init_client() only for advanced/manual scenarios.

Troubleshooting

“Config not loading” or “Key not found”

Verify target_site is set via one of these methods:
- settings.toml (recommended for persistent setup):
```
[default]
target_site = "example_site"
```
- Environment variable:
```
$env:target_site
```
  Should output your site name (e.g., example_site)
- Explicit argument in code:
```
init_api_client(target_site="example_site")
```

Check .secrets.toml has the site section with required auth keys:

Select-String -Path "src/britecore_sdk/settings/.secrets.toml" -Pattern "\[example_site\]"

Check .secrets.toml exists and has values:

Get-Content "src/britecore_sdk/settings/.secrets.toml"

Test config loading directly:

from britecore_sdk.settings.config import LoadClientSettings

settings = LoadClientSettings("example_site")
print(settings)  # Should show loaded config

Auth failures

Verify credentials in .secrets.toml:
- For API key: api_key is set
- For OAuth: both client_id and client_secret are set

Verify base_url matches the BriteCore instance:

from britecore_sdk import get_api_client
client = get_api_client()
print(client.base_url)  # Should be your BriteCore instance

For OAuth failures, check token endpoint is accessible:

# Verify endpoint format
# Should be: https://{base_url}/api/auth/oauth2/token

Adding New Sites

Edit settings.toml to add a site section (if needed):

[mysite]
# Optional: add non-sensitive configuration here

Edit .secrets.toml to add credentials and base_url:

[mysite]
base_url = "https://mysite.britecore.com"
client_id = "..."
client_secret = "..."
# or
api_key = "..."

Use:

client = BritecoreAPIClient("mysite")
client.init_client()

Private Maps Behavior

Some features in britecore_sdk rely on map files (such as policy, field, or agency maps) located in src/britecore_sdk/maps/. These files provide environment-specific mappings and are selected at runtime based on environment variables.

Map file selection:
- The environment variable system determines which map file is loaded (e.g., britecore_policy_name_map.py).
- If system is not set, the SDK may fall back to a default map or raise an error, depending on the utility.
- If the required map file is missing, a BritecoreError.KeyError or similar will be raised.
Required environment variables:
- system (selects the map variant)
- target_site (for config loading, may also affect map selection)
Fallback behavior:
- If a map file for the specified system is not found, the SDK may:
  - Use a default map (if implemented)
  - Raise a configuration or key error
- Always check logs for details if a map is missing or an env var is unset.
Troubleshooting:
- Ensure the correct system value is set in your environment.
- Verify that the corresponding map file exists in src/britecore_sdk/maps/.
- If you see errors about missing maps or unset variables, set the required env vars and restart your process.

Configuration Guide

Overview

Config Files

Canonical precedence table

SDK package default files (mainly for source clones)

`settings.toml` (Public)

`.secrets.toml` (Private)

Loading Configuration

Automatic (Recommended)

Via `get_api_client()` (Lazy, Recommended)

Environment Variables

Required Keys by Auth Mode

API Key Auth

OAuth Auth

Optional Utility Keys

Interactive menu behavior in IDE consoles

Validation

Per-Environment Setup

Development

CI/CD Pipelines

Production

API-only deployment checklist

Troubleshooting

“Config not loading” or “Key not found”

Auth failures

Adding New Sites

Private Maps Behavior

See Also

Configuration Guide

Overview

Config Files

Canonical precedence table

SDK package default files (mainly for source clones)

settings.toml (Public)

.secrets.toml (Private)

Loading Configuration

Automatic (Recommended)

Via get_api_client() (Lazy, Recommended)

Environment Variables

Required Keys by Auth Mode

API Key Auth

OAuth Auth

Optional Utility Keys

Interactive menu behavior in IDE consoles

Validation

Per-Environment Setup

Development

CI/CD Pipelines

Production

API-only deployment checklist

Troubleshooting

“Config not loading” or “Key not found”

Auth failures

Adding New Sites

Private Maps Behavior

See Also

`settings.toml` (Public)

`.secrets.toml` (Private)

Via `get_api_client()` (Lazy, Recommended)