Relying Party ID (domain, e.g., vouch.sh). Used as the WebAuthn RP ID.
VOUCH_RP_NAME
No
Vouch
Relying Party display name shown in browser prompts and UI.
VOUCH_DATABASE_URL
Yes
sqlite:vouch.db?mode=rwc
Database connection URL. Supports sqlite:, postgres:, and Aurora DSQL endpoints.
VOUCH_JWT_SECRET
Conditional
(empty)
JWT signing secret. Must be at least 32 characters. Must not consist of a single repeated character. Used to sign internal state tokens. Required unless VOUCH_JWT_HMAC_KMS_KEY_ID is set.
VOUCH_BASE_URL
No
https://{rp_id}
Base URL for this server. Auto-derived from VOUCH_RP_ID if not set (http://localhost:{port} for local dev, https://{rp_id} for production).
VOUCH_ORG_NAME
No
(none)
Organization name for branding in the UI. Falls back to VOUCH_RP_NAME if not set.
VOUCH_ALLOWED_DOMAINS
No
(none)
Comma-separated list of allowed email domains for enrollment (e.g., example.com,corp.example.com). If not set, all domains are allowed. Normalized to lowercase.
Configure one or more upstream IdPs (OIDC, SAML, or any mix) as a single unified list. VOUCH_IDPS holds a comma-separated list of slugs; each slug picks up its VOUCH_IDP_<SLUG>_* variables. Slugs match [a-z0-9-]{1,32} (no leading or trailing hyphen) and must be unique.
Variable
Required
Default
Description
VOUCH_IDPS
Yes
(none)
Comma-separated list of IdP slugs in display order (e.g., google,entra,corp-saml). At least one slug is required; the server refuses to start otherwise.
VOUCH_IDP_<SLUG>_TYPE
Yes (per IdP)
(none)
oidc or saml.
Hyphens in slugs become underscores in variable names: a slug of corp-saml becomes VOUCH_IDP_CORP_SAML_*.
The previous flat single-IdP variables — VOUCH_OIDC_ISSUER, VOUCH_OIDC_CLIENT_ID, VOUCH_OIDC_CLIENT_SECRET, VOUCH_OIDC_PROVIDERS, VOUCH_SAML_IDP_METADATA_URL, VOUCH_SAML_SP_ENTITY_ID, VOUCH_SAML_EMAIL_ATTRIBUTE, VOUCH_SAML_DOMAIN_ATTRIBUTE — are silently ignored. Setting them configures nothing; only the unified VOUCH_IDPS / VOUCH_IDP_<SLUG>_* variables above are read. See IdP Overview for the field-by-field mapping.
OIDC signing key content (base64-encoded PEM format, P-256 ECDSA). Used for signing access tokens and ID tokens with ES256 algorithm. If not set, an ephemeral key is generated on each server restart (not recommended for production).
VOUCH_OIDC_RSA_SIGNING_KEY
No
(auto-generate)
OIDC RSA signing key content (base64-encoded PEM format, RSA-3072). Used for signing ID tokens with RS256 algorithm per OIDC Core Section 3.1.3.7 and all AWS credential tokens (/v1/credentials/aws/token, serving both STS AssumeRoleWithWebIdentity and IAM Identity Center CreateTokenWithIAM). Minimum 3072-bit key enforced. If not set, an ephemeral key is generated on each server restart — AWS token verification then breaks after restarts and across multiple instances, so any deployment using the AWS integration must set this (or the KMS variant).
Background cleanup task interval in minutes. Set to 0 to disable automatic cleanup.
VOUCH_AUTH_EVENTS_RETENTION_DAYS
No
90
Retention period for authentication events in days. Events older than this are purged during cleanup.
VOUCH_OAUTH_EVENTS_RETENTION_DAYS
No
90
Retention period for OAuth usage and credential-issuance (aws_credential, github_credential, ssh_credential, token_exchange) events in days. Events older than this are purged during cleanup.
Comma-separated list of explicit CORS allowed origins for UI routes (e.g. https://app.example.com). Empty means same-origin only. Wildcard (*) is not supported — UI routes use credentialed cookie sessions, which are incompatible with wildcard origins per the CORS spec.
These variables configure the Vouch GitHub App integration for issuing GitHub tokens. The App ID, name, and key are required together for GitHub App functionality. OAuth client ID and secret are additionally needed for GitHub user authentication.
Variable
Required
Default
Description
VOUCH_GITHUB_APP_ID
No
(none)
GitHub App ID (numeric, assigned when creating the app on github.com).
VOUCH_GITHUB_APP_NAME
No
(none)
GitHub App name (the slug from github.com/apps/{name}).
VOUCH_GITHUB_APP_KEY
No
(none)
GitHub App private key (PEM format, RSA). Can use literal \n for newlines.
VOUCH_GITHUB_WEBHOOK_SECRET
No
(none)
GitHub webhook secret for verifying webhook signatures (HMAC-SHA256).
VOUCH_GITHUB_APP_CLIENT_ID
No
(none)
GitHub App Client ID for OAuth user authentication. Found in GitHub App settings (different from the numeric App ID).
VOUCH_GITHUB_APP_CLIENT_SECRET
No
(none)
GitHub App Client Secret for OAuth user authentication.
When both VOUCH_TLS_CERT and VOUCH_TLS_KEY are set, the server listens on port 443 (HTTPS) with an automatic HTTP-to-HTTPS redirect on port 80. The VOUCH_LISTEN_ADDR setting is ignored when TLS is configured.
Variable
Required
Default
Description
VOUCH_TLS_CERT
No
(none)
TLS certificate (base64-encoded PEM).
VOUCH_TLS_KEY
No
(none)
TLS private key (base64-encoded PEM). Required if VOUCH_TLS_CERT is set.
These optional variables configure descriptive metadata published in the OAuth 2.0 Protected Resource Metadata document at /.well-known/oauth-protected-resource.
Variable
Required
Default
Description
VOUCH_RESOURCE_NAME
No
Vouch
Human-readable name of this protected resource.
VOUCH_RESOURCE_DOCUMENTATION
No
https://vouch.sh/docs/
URL of developer documentation for this protected resource.
The Vouch CLI resolves its user-facing language once at startup. Resolution checks the following sources in order; the first that parses as a BCP 47 language tag wins.
Variable
Required
Default
Description
--lang <BCP-47>
No
(none)
Global CLI flag (highest priority). Example: vouch --lang en-US enroll.
Standard POSIX locale variable; overrides every other LC_*.
LC_MESSAGES
No
(POSIX)
Standard POSIX locale variable for message translations.
LANG
No
(POSIX)
Standard POSIX locale variable used when LC_* are unset.
If none of the above resolve, the CLI falls through to the operating system’s default locale via sys-locale. When that is also unavailable (e.g., a minimal container with no locale configured), the CLI falls back to en-US. POSIX-style locale strings (en_US.UTF-8, ca_ES@valencia) are normalized by stripping the .<codeset> and @<modifier> suffixes and replacing _ with -.
Machine-readable output (vouch status --json, vouch status --shell, vouch env, credential helpers) is never affected by the locale — those payloads are consumed by other tools and remain stable across locales. Only human-facing prompts, success/failure messages, error messages, and --help text honor the negotiated locale.
This release ships en-US only; the catalog scaffolding lets translations land in isolated PRs without changing the CLI surface.