Configuration File

This document describes the supported configuration file (YAML/JSON) keys that FigChain clients accept. Clients load config files and then apply environment variable and programmatic overrides. Use this file as a reference for what you can put in figchain.yaml / figchain.json.

Core fields

  • base_url (string)
  • Base API URL. Default: https://app.figchain.io/api/
  • Env var: FIGCHAIN_URL (canonical)
  • long_polling_url (string)
  • Optional endpoint used for long-polling.
  • Env var: FIGCHAIN_LONG_POLLING_URL
  • environment_id (string / UUID) — REQUIRED
  • Env var: FIGCHAIN_ENVIRONMENT_ID
  • namespaces (array of strings)
  • Namespaces to bootstrap and poll. Clients accept namespace (single string) as legacy.
  • Env var: FIGCHAIN_NAMESPACES (comma-separated)
  • as_of_timestamp (string)
  • Optional timestamp for reproducible bootstrap.

Polling & retry

  • polling_interval (duration or integer ms)
  • Go accepts duration strings (e.g. 60s) or ms via FIGCHAIN_POLLING_INTERVAL_MS.
  • Java/Python use milliseconds: FIGCHAIN_POLLING_INTERVAL_MS.
  • max_retries (int) — default 3
  • Env var: FIGCHAIN_MAX_RETRIES
  • retry_delay (duration or integer ms)
  • Env var: FIGCHAIN_RETRY_DELAY_MS (ms)

Authentication

  • client_secret (string)
  • Shared-secret authentication. Env var: FIGCHAIN_CLIENT_SECRET
  • Private-key auth (JWT signing):
  • auth_private_key_path (string) — path to PEM file
  • auth_private_key_pem (string) — PEM content inline
  • auth_client_id / auth_credential_id (string) — identifiers used in JWT
  • Env vars: FIGCHAIN_AUTH_PRIVATE_KEY_PATH, FIGCHAIN_AUTH_PRIVATE_KEY_PEM, FIGCHAIN_AUTH_CLIENT_ID, FIGCHAIN_AUTH_CREDENTIAL_ID

S3 Resilience (Backups)

  • backup_enabled (bool) — default false — Env var FIGCHAIN_BACKUP_ENABLED
  • backup_bucket (string) — FIGCHAIN_BACKUP_BUCKET
  • backup_prefix (string) — FIGCHAIN_BACKUP_PREFIX
  • backup_region (string) — default us-east-1 — FIGCHAIN_BACKUP_REGION
  • backup_endpoint (string) — custom endpoint (MinIO) — FIGCHAIN_BACKUP_ENDPOINT
  • backup_path_style / backup_path_style_access (bool) — FIGCHAIN_BACKUP_PATH_STYLE_ACCESS
  • backup_private_key_path (string) — FIGCHAIN_BACKUP_PRIVATE_KEY_PATH

Encryption / decryption

  • encryption_private_key_path (string)
  • Path to private key used to decrypt encrypted Figs/envelopes.
  • Env var: FIGCHAIN_ENCRYPTION_PRIVATE_KEY_PATH

Bootstrap strategy

  • bootstrap_strategy (string)
  • Values: server, server-first, backup, hybrid (Java may use SERVER_FIRST enum names).
  • Env var: FIGCHAIN_BOOTSTRAP_STRATEGY / FIGCHAIN_BOOTSTRAP_MODE

Other

  • tenant_id (string) — FIGCHAIN_TENANT_ID
  • use_long_polling (bool) — use long-polling transport when supported

Precedence

  • Programmatic options (builder / function params) override
  • Environment variables override
  • Config file (YAML/JSON) provides defaults
  • Library defaults apply if unset

Example figchain.yaml

base_url: "https://app.figchain.io/api/"
environment_id: "00000000-0000-0000-0000-000000000000"
namespaces:
  - default
polling_interval: "60s"         # Go accepts duration; Java/Python expect ms env vars
max_retries: 3
retry_delay: "1s"
# Private key auth
auth_private_key_path: "/etc/figchain/auth.pem"
auth_private_key_pem: |
  -----BEGIN PRIVATE KEY-----
  ...
  -----END PRIVATE KEY-----

backup_enabled: true
backup_bucket: "my-figchain-backups"
encryption_private_key_path: "/etc/figchain/encryption.pem"
bootstrap_strategy: "server-first"

Compatibility notes

  • The canonical env var names are the FIGCHAIN_* names listed above. Java and Python already use these canonical names. The Go client now accepts them as compatibility aliases in addition to its original base_url/polling_interval keys (supports duration strings).
  • Use millisecond env vars (FIGCHAIN_POLLING_INTERVAL_MS, FIGCHAIN_RETRY_DELAY_MS) for Java/Python; the Go client will convert ms env vars into Go durations.