All ProtocolSoup backend services share a common set of core variables. Individual services add protocol-specific configuration on top.
| Variable | Default | Description |
|---|
SHOWCASE_BASE_URL | http://localhost:8080 | Public URL used in metadata, redirect URIs, and token issuer claims. Set this to your externally reachable URL. |
SHOWCASE_LISTEN_ADDR | :8080 | Address and port the service binds to. |
SHOWCASE_CORS_ORIGINS | http://localhost:3000,http://localhost:5173 | Comma-separated list of allowed CORS origins for browser clients. |
SHOWCASE_ENV | demo | Runtime environment. |
SHOWCASE_MOCK_IDP | true | Enable built-in mock identity provider with demo users and clients. |
SHOWCASE_DEBUG | false | Enable debug logging. |
SHOWCASE_PALETTE_DB | (empty — palette disabled) | Path to the prebuilt palette SQLite index. Required in SHOWCASE_ENV=production when palette search is enabled. Docker images built from Dockerfile.backend and Dockerfile.fly default to /app/palette.db. See Palette content index. |
| Variable | Default | Description |
|---|
FEDERATION_SERVICE_URL | - | Upstream URL for the federation service. |
SCIM_SERVICE_URL | - | Upstream URL for the SCIM service. |
SSF_SERVICE_URL | - | Upstream URL for the SSF service. |
SPIFFE_SERVICE_URL | - | Upstream URL for the SPIFFE service. |
VC_SERVICE_URL | - | Upstream URL for the VC service (if separate from federation). |
| Variable | Default | Description |
|---|
SCIM_API_TOKEN | - | Bearer token required for all SCIM API requests. Set this to any string; clients must send it in the Authorization: Bearer <token> header. |
| Variable | Default | Description |
|---|
SSF_RECEIVER_TOKEN | - | Bearer token the receiver accepts for event delivery. |
| Variable | Default | Description |
|---|
SPIFFE_AGENT_SOCKET | /run/spire/sockets/agent/agent.sock | Path to the SPIRE agent Workload API socket. Required for full SPIRE mode. |
SPIFFE_TRUST_DOMAIN | protocolsoup.local | SPIFFE trust domain. |
| Variable | Default | Description |
|---|
WALLET_TARGET_BASE_URL | https://protocolsoup.com | URL of the VC verifier service for OID4VP submissions. |
WALLET_ALLOWED_CORS_ORIGINS | https://protocolsoup.com,https://www.protocolsoup.com,https://protocolsoup.fly.dev | Comma-separated allowed browser origins. |
WALLET_DEFAULT_SUBJECT | did:example:wallet:alice | Default DID subject for demo sessions. |
WALLET_SESSION_TTL | Server default | Go duration (e.g. 30m) for session lifetime. |
WALLET_STRICT_SESSION_ISOLATION | true | Enforce strict session boundaries between demo runs. |
WALLET_TRUSTED_VERIFIER_ATTESTATION_ISSUERS | (empty) | Comma-separated issuer URLs the wallet trusts for verifier_attestation request validation. |
| Variable | Default | Description |
|---|
OID4VP_VERIFIER_ATTESTATION_ISSUER | <SHOWCASE_BASE_URL>/oid4vp/verifier-attestation | Issuer URL published for verifier attestation metadata and JWKS. |
OID4VP_VERIFIER_ATTESTATION_CLIENT_ID | verifier_attestation:<SHOWCASE_BASE_URL host> | Verifier client_id used when client_id_scheme=verifier_attestation. |
OID4VP_VERIFIER_ATTESTATION_PRIVATE_KEY_PEM | Ephemeral in-memory key | PEM-encoded stable signing key for verifier attestation JWTs and JWKS. Set this in production so attestation validation survives restarts and deploys. |
OID4VP_X509_SANDNS_CLIENT_ID | x509_san_dns:<SHOWCASE_BASE_URL host> | Verifier client_id used when client_id_scheme=x509_san_dns. Must match a DNS SAN on the leaf certificate. |
OID4VP_X509_SANDNS_CERT_CHAIN_PEM | Ephemeral self-signed chain | PEM-encoded certificate chain added to the request object’s x5c JOSE header. When unset, an ephemeral CA + leaf chain is generated at startup using the deployment hostname as the leaf SAN. |
OID4VP_X509_SANDNS_PRIVATE_KEY_PEM | Ephemeral key | PEM-encoded private key matching the leaf certificate used for x509_san_dns request signing. When unset, generated alongside the ephemeral chain. Set both PEM variables in production for certificate continuity across restarts. |
SHOWCASE_BASE_URL is the most important variable. It determines the issuer, entity ID, redirect URIs, and metadata URLs across all protocols. Always set it to the URL your clients will actually use.- When running behind a reverse proxy or load balancer, set
SHOWCASE_BASE_URL to the external URL (e.g. https://protocolsoup.example.com) rather than the internal address.
SHOWCASE_CORS_ORIGINS must include the origin of your frontend. If the UI is at https://app.example.com, add that origin.- For SCIM, set
SCIM_API_TOKEN to any secret string. Clients must include Authorization: Bearer <your-token> on every request.
- To enable real
verifier_attestation OID4VP flows, publish the verifier issuer URL from the verifier service and add that issuer to the wallet’s WALLET_TRUSTED_VERIFIER_ATTESTATION_ISSUERS allow-list.
x509_san_dns works out of the box. When the PEM env vars are unset, an ephemeral ECDSA P-256 CA + leaf certificate chain is generated at startup with the leaf SAN bound to the deployment hostname from SHOWCASE_BASE_URL. Provide your own PEM chain and key for production certificate continuity.
