Configuration

TapPass is configured entirely through environment variables. All variables are read with the TAPPASS_ prefix (Conjur uses CONJUR_; telemetry uses standard SENTRY_* / OTEL_* names).

Loading order: .tappass-secrets.env and .env in the working directory are auto-loaded at startup (secrets file first, neither overrides already-set variables). Every sensitive key also supports a Docker-secrets _FILE variant — e.g. TAPPASS_ADMIN_API_KEY_FILE=/run/secrets/tappass_admin_key reads the secret from that file. _FILE variants exist for TAPPASS_ADMIN_API_KEY, TAPPASS_JWT_SECRET, TAPPASS_VAULT_KEY, TAPPASS_VAULT_DEK, OPENAI_API_KEY, ANTHROPIC_API_KEY, DASHSCOPE_API_KEY, TAPPASS_SSO_GOOGLE_CLIENT_SECRET, TAPPASS_SSO_AZURE_CLIENT_SECRET, and POSTGRES_PASSWORD/REDIS_PASSWORD, among others.

Server

Variable	Default	Description
TAPPASS_HOST	0.0.0.0	Bind address for the FastAPI app
TAPPASS_PORT	9620	TCP port the gateway listens on
TAPPASS_DEBUG	false	Verbose error responses. Never true in production — leaks stack traces
TAPPASS_CORS_ORIGINS	—	Comma-separated CORS origins (read in api/main.py); * entries are stripped
TAPPASS_DASHBOARD_HOSTS	—	Comma-separated dashboard host allowlist (*.eu.tappass.ai wildcards); empty = host scoping off
TAPPASS_GATEWAY_HOSTS	—	Comma-separated gateway host allowlist; empty = off
TAPPASS_HOST_SCOPE_ALLOW_LOCALHOST	true	Dev bypass for host-scoping middleware; set false in production
TAPPASS_WORKSPACE_DOMAINS	—	Per-workspace URL routing: region=suffix,... (e.g. eu=eu.tappass.ai,us=us.tappass.ai)
TAPPASS_PRODUCTION	false	Explicit production-mode flag; also auto-detected from TAPPASS_ENV=production
TAPPASS_PUBLIC_URL / TAPPASS_BASE_URL	http://localhost:9620	Public base URL used to build external links (invitation emails, connector OAuth callbacks, MCP connect URLs). Set this when self-hosting on a custom domain or those links won’t resolve
TAPPASS_CAPTURE_IO	1	Capture request/response bodies into the audit trail. Set 0 to record metadata only (stricter privacy)
TAPPASS_GATEWAY_MODEL_TIMEOUT_SEC	180	Timeout for upstream provider calls made by the gateway
TAPPASS_RESEND_API_KEY / TAPPASS_RESEND_FROM_EMAIL	—	Email-provider key + from-address for outbound invitation emails; unset = email sending off

Auth

Variable	Default	Description
TAPPASS_ADMIN_API_KEY	—	Admin API key. Empty = authentication disabled (dev only)
TAPPASS_JWT_SECRET	—	JWT signing key for capability tokens. Empty = ephemeral per-process key (dev); must be ≥ 32 chars in production
TAPPASS_JWT_ISSUER	tappass	JWT iss claim
TAPPASS_SESSION_TTL_HOURS	8	Login session lifetime
TAPPASS_API_KEY_DEFAULT_TTL_DAYS	90	Agent API key default lifetime; 0 = no expiry
TAPPASS_LOCKOUT_THRESHOLD	5	Failed logins before lockout fires
TAPPASS_LOCKOUT_WINDOW_SECONDS	300	Sliding window over which failures count
TAPPASS_LOCKOUT_DURATION_SECONDS	900	How long a locked account stays locked

Database

Variable	Default	Description
DATABASE_URL	—	Required. PostgreSQL DSN; boot refuses without it
TAPPASS_DB_POOL_MIN_SIZE	2	Min idle connections in the asyncpg pool
TAPPASS_DB_POOL_MAX_SIZE	10	Max connections in the asyncpg pool
TAPPASS_DB_ASYNC_POOL_MIN_SIZE	1	Min idle connections in the async (govern hot-path) pool
TAPPASS_DB_ASYNC_POOL_MAX_SIZE	5	Max connections in the async pool
TAPPASS_DB_POOL_TIMEOUT_SECONDS	30.0	Wait for a free pool connection before erroring
TAPPASS_KV_URL	—	Redis URL (redis://…) for the shared KV store; unset = in-memory
TAPPASS_RUN_MIGRATIONS_ON_BOOT	off	1/true/yes runs migrations at startup (advisory-locked); leave off in production
TAPPASS_ALLOW_EPHEMERAL	false	Test-only escape hatch: boot without DATABASE_URL using in-memory stores. Never in production

Vault

Variable	Default	Description
TAPPASS_VAULT_KEY	—	Master key for credential-vault encryption at rest. Empty = publicly known dev key
TAPPASS_TOKEN_KEY_FILE	—	Path to the PEM used to sign capability tokens. Empty = ephemeral in-memory key
TAPPASS_VAULT_KEY_KMS	—	KMS key URI for envelope encryption (checked before TAPPASS_VAULT_KEY)
TAPPASS_VAULT_DEK	—	Base64 KMS-wrapped data-encryption key (AWS/GCP envelope mode)
TAPPASS_SECRETS_BACKEND	—	External secrets backend name; conjur = CyberArk Conjur

When Conjur is configured (CONJUR_APPLIANCE_URL set), sensitive fields are overlaid from the vault at startup. Conjur connection settings use the CONJUR_ prefix: CONJUR_APPLIANCE_URL, CONJUR_ACCOUNT (default), CONJUR_VARIABLE_PREFIX (tappass), CONJUR_CACHE_TTL (300), CONJUR_FAIL_CLOSED (false), plus authn-method variables (CONJUR_AUTHN_JWT_TOKEN, CONJUR_AUTHN_API_KEY, …).

LLM judge

Any LiteLLM provider/model string works (gpt-4o-mini, mistral/mistral-small-latest, ollama/llama3.1, azure/gpt-4o-mini, anthropic/claude-3-haiku-20240307, …).

Variable	Default	Description
TAPPASS_LLM_JUDGE_MODEL	gpt-4o-mini	Primary judge model
TAPPASS_LLM_JUDGE_ENABLED	true	Master switch for the LLM judge
TAPPASS_LLM_JUDGE_FALLBACK_MODEL	—	Fallback when the primary fails
TAPPASS_OLLAMA_API_BASE	http://localhost:11434	Base URL of the local Ollama server (only for ollama/* models)
OPENAI_API_KEY / ANTHROPIC_API_KEY / DASHSCOPE_API_KEY	—	Provider credentials consumed by LiteLLM
TAPPASS_EU_DATA_RESIDENCY	false	Restrict the judge to EU-hosted models (TAPPASS_EU_ALLOWED_JUDGE_MODELS)

Mandates (capability tokens)

Variable	Default	Description
TAPPASS_DEFAULT_TOKEN_TTL_SECONDS	60	Default token lifetime when the caller omits one
TAPPASS_MAX_TOKEN_TTL_SECONDS	300	Hard ceiling on token TTL; mint requests above this are rejected
TAPPASS_DEFAULT_MAX_INVOCATIONS	10	Default tool-invocation cap per token
TAPPASS_MAX_INVOCATIONS_LIMIT	100	Hard ceiling on per-token invocation counts

Audit

Variable	Default	Description
TAPPASS_AUDIT_FILE	data/audit.jsonl	Path to the JSONL audit log
TAPPASS_AUDIT_ROTATION_MAX_MB	100	Rotate the audit file above this size
TAPPASS_AUDIT_RETENTION_DAYS	365	Auto-purge audit records older than this (GDPR storage limitation); 0 = forever
TAPPASS_AUDIT_LOG_PARAMS	false	Include request params in audit records. Never true in production
TAPPASS_AUDIT_SIGNING_KEY	—	Path to the audit signing key PEM; unset = auto-generated in TAPPASS_KEYS_DIR
TAPPASS_AUDIT_KEY_PASSWORD	—	Encrypts the signing-key PEM at rest
TAPPASS_KEYS_DIR	keys	Directory for auto-generated audit signing keys

SSO (OIDC)

Variable	Default	Description
TAPPASS_SSO_PROVIDERS	—	Comma-separated active providers, e.g. google,azure. Empty = SSO off
TAPPASS_SSO_REDIRECT_URI	—	OAuth redirect URI shared across providers
TAPPASS_SSO_ALLOWED_DOMAINS	—	Comma-separated email-domain allowlist; empty = allow any
TAPPASS_SSO_GOOGLE_CLIENT_ID / TAPPASS_SSO_GOOGLE_CLIENT_SECRET	—	Google OAuth client
TAPPASS_SSO_AZURE_CLIENT_ID / TAPPASS_SSO_AZURE_CLIENT_SECRET	—	Azure AD application client
TAPPASS_SSO_AZURE_TENANT_ID	organizations	Azure AD tenant; organizations for multi-tenant B2B
TAPPASS_GOOGLE_CLIENT_IDS	—	Extra trusted Google audiences for /auth/google-token (e.g. a gcloud CLI client)
TAPPASS_GOOGLE_TOKEN_ALLOW_ANY_AUDIENCE	false	Dev only — disables audience verification; production refuses to start

SAML 2.0

Variable	Default	Description
TAPPASS_SAML_ENABLED	false	Master switch — enables /saml/acs + /saml/metadata
TAPPASS_SAML_ENTITY_ID	https://tappass.company.com/saml/metadata	SP entity ID published in SAML metadata
TAPPASS_SAML_ACS_URL	http://localhost:9620/saml/acs	Assertion Consumer Service URL
TAPPASS_SAML_IDP_SSO_URL	—	IdP SSO endpoint
TAPPASS_SAML_IDP_CERT	—	Base64 X.509 cert for IdP signature verification
TAPPASS_SAML_IDP_METADATA_URL	—	IdP metadata URL (alternative to pinning the cert)
TAPPASS_SAML_ALLOWED_DOMAINS	—	Email-domain allowlist for SAML sign-in
TAPPASS_SAML_DEFAULT_ROLE	user	Role when no group→role mapping fires
TAPPASS_SAML_WANT_ASSERTIONS_SIGNED	true	Require IdP-signed assertions (enforced in production)
TAPPASS_SAML_WANT_RESPONSE_SIGNED	true	Require IdP-signed responses (enforced in production)
TAPPASS_SAML_ROLE_MAPPING	—	Group→role mapping: group=role,group=role

SIEM export

Variable	Default	Description
TAPPASS_SIEM_URL	—	SIEM endpoint; unset = export disabled
TAPPASS_SIEM_DESTINATION	webhook	Destination type
TAPPASS_SIEM_AUTH_TOKEN	—	Bearer token for the SIEM endpoint

Alerting

Variable	Default	Description
TAPPASS_ALERT_WEBHOOK_URL	—	Slack/Teams/generic webhook; unset = alerting disabled
TAPPASS_ALERT_WEBHOOK_TYPE	slack	slack | teams | generic
TAPPASS_ALERT_MIN_SEVERITY	block	block | detect | all

WebAuthn (fingerprint approval)

Variable	Default	Description
TAPPASS_WEBAUTHN_RP_ID	tappass.ai	Relying-Party identifier — the eTLD+1 the browser sees; localhost for dev
TAPPASS_WEBAUTHN_RP_NAME	TapPass	Display name on the credential-create prompt
TAPPASS_WEBAUTHN_EXPECTED_ORIGIN	https://app.tappass.ai	Origin the WebAuthn assertion must match
TAPPASS_WEBAUTHN_CHALLENGE_TTL_SECONDS	300	Challenge validity window

Rate limiting

Variable	Default	Description
TAPPASS_RATE_LIMIT_ENABLED	true	Master switch; disable only for local testing
TAPPASS_RATE_LIMIT_REQUESTS_PER_MINUTE	600	Per-identity request budget
TAPPASS_RATE_LIMIT_TOKENS_PER_MINUTE	300	Per-agent /chat/completions budget
TAPPASS_RATE_LIMIT_BURST	100	Burst allowance over the per-minute rate
TAPPASS_RATE_LIMIT_ORG_REQUESTS_PER_MINUTE	3000	Aggregate per-org budget; 0 = disabled

Defaults are sized for an agent doing real work (30–60 tool calls/min per Claude Code session); tighten per deployment once the agent footprint is known.

Telemetry

Variable	Default	Description
SENTRY_DSN	—	Error/trace reporting (unset = off)
TAPPASS_ENABLE_DEV_TELEMETRY	false	In non-production, Sentry/PostHog also require this set to 1 (production auto-enables when the keys are present)
SENTRY_TRACES_SAMPLE_RATE / SENTRY_PROFILES_SAMPLE_RATE	0.2 / 0.1	Transaction sampling rates once SENTRY_DSN is set
TAPPASS_SENTRY_PROFILE_SAMPLE_RATE	0.0	Continuous-profiling session sample rate (0.0–1.0); recommend 0.1 on staging
TAPPASS_POSTHOG_KEY	—	PostHog project token (phc_…); unset = off
TAPPASS_POSTHOG_HOST	https://eu.i.posthog.com	PostHog ingestion host (EU cloud default)
OTEL_EXPORTER_OTLP_ENDPOINT	—	OTLP/gRPC collector endpoint; setting it enables push export and tracing
TAPPASS_OTLP_AUDIT_SPANS	—	Set (1/true) with an OTLP endpoint to export every governance decision as an OTel span; opt-in, off by default (see Observability)
TAPPASS_ENV	development	deployment.environment resource attribute; production also triggers the production gate

Branding (white-label)

Served by GET /api/workspace/branding. Defaults are the canonical TapPass branding.

Variable	Default	Description
TAPPASS_BRAND_NAME	TapPass	Product name on login / sidebar
TAPPASS_BRAND_TAGLINE	AI Governance Platform	Tagline under the brand name
TAPPASS_BRAND_LOGO_URL	/tappass-logo.svg	Logo URL; empty = inline wordmark
TAPPASS_BRAND_ACCENT	#15803d	Accent colour hex
TAPPASS_BRAND_FOOTER	—	Static footer text (empty = live © {year} {brand_name})

Multi-region

Variable	Default	Description
TAPPASS_REGION	—	Short region code, e.g. eu-west
TAPPASS_REGION_LABEL	—	Human-readable region name, e.g. EU Frankfurt