Skip to content

Configuration

Quick Start

Recommended: Use .env file

The easiest way to get started is to copy .env.example to .env and fill in your tokens. The SDK will load it automatically: 

cp .env.example .env
# Edit .env and add your tokens

Configuration File

The SDK reads configuration from a JSON file. Start with the included template:

cp config/default.json my_config.json

Or generate a sample programmatically:

from silo_sdk.utils.config import create_sample_config
create_sample_config("my_config.json")

Configuration Keys

Key Required Default Description
API_URL No https://extapi.authentic8.com Base URL for the Authentic8 API
ADMIN_TOKEN For browsing/org — Token for BrowsingAPI and OrgManagementAPI
SYNC_TOKEN For user mgmt — Token for UserManagementAPI
FILE_TOKEN For file storage — Token for FileAPI
LOG_TOKEN For log extraction — Token for LogExtractionAPI
SCRAPE_TOKEN For harvesting — Token for HarvesterAPI
BUCKET_ID For file storage — Default file storage bucket ID
CATCHALL_USER For browsing — Default Silo username for browsing isolation contexts
TOP_ORG For the MCP server — Top-level organization name used as the org argument in API calls. a8_validate_config treats it as required, a8_health_check probes ADMIN_TOKEN against it, and a8_get_api_info reports it.
ORG_VANITY_URL No — Organization vanity URL
REQUEST_TIMEOUT No 30 HTTP request timeout (seconds) for every API except log extraction
LOG_EXTRACT_TIMEOUT No (unset) HTTP request timeout (seconds) for LogExtractionAPI only. Ships blank in config/default.json; when unset, LogExtractionAPI falls back to 600 seconds — see Log extraction timeout
MAX_RETRIES No 3 Retry count on transient errors
RETRY_DELAY No 5 Seconds between retries
LOG_LEVEL No INFO SDK log level (DEBUG, INFO, WARNING, ERROR)
ENABLE_ENCRYPTION No false Enable result encryption (requires RSA key setup)
DEFAULT_DEST_PATH No / Default storage destination path for harvest results
DEBUG_MODE No false Enable debug logging
DEFAULT_MAX_USES No 1 Default max_uses for research session contexts created via a8_create_research_session MCP tool
ENABLE_STATUS_CACHE No false Cache harvest task status responses in HarvesterAPI, so repeated status polls for the same task ID reuse the last response instead of calling the API
STATUS_CACHE_TTL No 30 Lifetime in seconds of a cached harvest task status entry. Only consulted when ENABLE_STATUS_CACHE is true. 0 disables caching; validate_harvester_config() rejects values above 300.
RATE_LIMIT No {"requests_per_second": 10, "burst": 20} Declared rate-limit budget. validate_harvester_config() checks the shape (both values must be positive), but the SDK does not throttle requests on its own — enforce the limit in your own code or at a proxy.
DEFAULT_EGRESS_INFO No {"name": "New York, NY"} Default egress location, used by the bundled scripts and examples when --research is requested without an explicit egress. Validated against the known egress locations.
DEFAULT_POLICY No See config/default.json Default browsing policy — a list of {"type": ..., "params": [...]} entries. Read by the bundled examples and reported by a8_validate_config as an optional key; API methods take the policy as an argument rather than reading this key.
ENABLE_REQUEST_LOGGING No false Present in the shipped config files as a placeholder. No SDK code reads it, so setting it currently has no effect — use LOG_LEVEL=DEBUG for verbose request logging.

TLS verification is not configurable

Certificates are always verified, against the certifi trust store, on both the synchronous and the aiohttp code paths. There is no setting that turns this off. Earlier releases shipped a VERIFY_SSL key in config/default.json that no SDK code read; it has been removed rather than wired up, so nothing suggests a switch that does not exist. If you are terminating TLS at a proxy with a private CA, add that CA to the system or certifi trust store rather than disabling verification.

ORG_VANITY_URL is not the API org name

TOP_ORG holds the API org name (e.g. MyCompany) that commands such as org.get and listusers expect. ORG_VANITY_URL is the SSO vanity slug — a different value the API does not accept as an org name.

Log extraction timeout

LogExtractionAPI uses its own request timeout, LOG_EXTRACT_TIMEOUT. The key ships blank in config/default.json, and the client falls back to 600 seconds when it is unset. The server serializes extracts behind a per-extract lock with a 600-second TTL, so a client that gives up sooner abandons a request that is still running while the lock stays held — every retry then fails until the TTL expires. Pinning the client timeout to the lock TTL means anything that does time out has also released its lock.

Two rules govern how it combines with REQUEST_TIMEOUT:

  • The default raises the extraction timeout but never lowers one already set higher. If REQUEST_TIMEOUT is above 600 — as it might be if you raised it to work around the previous 30-second extraction limit — extraction keeps that larger value.
  • An explicit LOG_EXTRACT_TIMEOUT wins outright, including a value below REQUEST_TIMEOUT, because setting it is a deliberate choice rather than an inherited default.

REQUEST_TIMEOUT continues to govern every other API. A non-numeric or non-positive LOG_EXTRACT_TIMEOUT raises ConfigurationError when the configuration is loaded or the client is constructed, rather than failing on the first request.

Environment Variables

All configuration values can be set via environment variables. The A8_ prefix is the convention for all SDK variables:

Environment Variable Config Key Description
A8_API_URL API_URL API base URL
A8_ADMIN_TOKEN ADMIN_TOKEN Browsing / org management token
A8_SYNC_TOKEN SYNC_TOKEN User management token
A8_FILE_TOKEN FILE_TOKEN File storage token
A8_LOG_TOKEN LOG_TOKEN Log extraction token
A8_SCRAPE_TOKEN SCRAPE_TOKEN Harvesting token
A8_BUCKET_ID BUCKET_ID Default file storage bucket
A8_CATCHALL_USER CATCHALL_USER Default Silo username for browsing contexts
A8_ORG_VANITY_URL ORG_VANITY_URL Organization vanity URL
A8_LOG_LEVEL LOG_LEVEL SDK log level
A8_REQUEST_TIMEOUT REQUEST_TIMEOUT HTTP request timeout in seconds (fallback: 30)
A8_LOG_EXTRACT_TIMEOUT LOG_EXTRACT_TIMEOUT Log extraction request timeout in seconds (fallback: 600)
A8_MAX_RETRIES MAX_RETRIES Retry count on transient errors (fallback: 3)
A8_RETRY_DELAY RETRY_DELAY Seconds between retries (fallback: 5)
A8_TOP_ORG TOP_ORG Top-level org name, also read by the bundled scripts (session_report, export_logs, etc.)
A8_TARGET_ORG (script env var) Destination org for move_users.py
A8_DEFAULT_MAX_USES DEFAULT_MAX_USES Default max_uses for a8_create_research_session MCP tool (fallback: 1)

Environment Variable Substitution

Config values support bash-style env var substitution:

{
  "API_URL": "${A8_API_URL:-https://extapi.authentic8.com}",
  "ADMIN_TOKEN": "${A8_ADMIN_TOKEN}",
  "SYNC_TOKEN": "${A8_SYNC_TOKEN}",
  "FILE_TOKEN": "${A8_FILE_TOKEN}",
  "LOG_TOKEN": "${A8_LOG_TOKEN}",
  "SCRAPE_TOKEN": "${A8_SCRAPE_TOKEN}",
  "CATCHALL_USER": "${A8_CATCHALL_USER}"
}
  • ${VAR_NAME} — required; raises ConfigurationError if not set
  • ${VAR_NAME:-default} — optional; falls back to default if not set

Environment Files (.env)

The SDK uses python-dotenv to automatically load .env files:

# .env (never commit this file)
A8_ADMIN_TOKEN=your-admin-token
A8_SYNC_TOKEN=your-sync-token
A8_FILE_TOKEN=your-file-token
A8_LOG_TOKEN=your-log-token
A8_SCRAPE_TOKEN=your-scrape-token
A8_BUCKET_ID=your-bucket-id
A8_CATCHALL_USER=your-catchall-username
A8_TOP_ORG=your-org-name

See .env.example in the repository root for a complete template:

cp .env.example .env
# then fill in your values

Never commit .env files

.env is listed in .gitignore. Keep tokens and usernames out of source control. The committed config/default.json uses only ${A8_*} env var references — no real values.

Loading Configuration

from silo_sdk import load_config

config = load_config("config/default.json")


export A8_CONFIG_ENV=development

# Call load_config() with no argument to get the overlay:
# loads config/default.json, then overlays config/development.json
config = load_config()

Passing a path disables the overlay

load_config("config/default.json") loads exactly that one file. The A8_CONFIG_ENV overlay is applied only on the no-argument form.

from silo_sdk import create_config
import os

config = (create_config()
    .with_api_url("https://extapi.authentic8.com")
    .with_browsing_token(os.environ["A8_ADMIN_TOKEN"])
    .with_sync_token(os.environ["A8_SYNC_TOKEN"])
    .with_timeout(30)
    .build())

Multi-Environment Setup

config/
  default.json      # base values with env var refs — version-controlled
  production.json   # production overrides — version-controlled
  development.json  # dev overrides — gitignored
  qa.json           # QA overrides — gitignored

Select the environment with the A8_CONFIG_ENV variable. The name becomes the overlay filename, so it must contain only letters, digits, hyphens, and underscores:

export A8_CONFIG_ENV=development   # loads default.json then development.json
export A8_CONFIG_ENV=qa            # loads default.json then qa.json
export A8_CONFIG_ENV=production    # loads default.json then production.json

No overlay is applied when A8_CONFIG_ENV is unset

There is no implicit default environment. With the variable unset, load_config() reads config/default.json alone. An overlay file that does not exist is skipped silently, so a typo in the environment name is not an error — it just means no overrides are applied.

The same variable also selects a second environment file for secrets: .env is loaded first, then .env.{A8_CONFIG_ENV} on top of it. A8_CONFIG_ENV must come from the shell or process environment rather than from .env, so a value checked into .env cannot silently override your profile selection.

Keep default.json clean

config/default.json is version-controlled and should never contain real values. Use ${A8_*} env var references for all secrets and site-specific settings. Put actual values in your .env file or environment-specific config files (all gitignored).