Configuration

All configuration is done via environment variables.

Core

Variable	Required	Default	Description
BASE_URL	✅	—	Public URL of the Taco instance (e.g. https://taco.example.com)
AUTH_SECRET	✅	—	32-byte random secret for session signing. Generate with openssl rand -base64 32

Database

Variable	Required	Default	Description
DATABASE_URL	✅	—	PostgreSQL connection string (e.g. pgsql://user:pass@host:5432/taco)
DATABASE_DIALECT	—	postgresql	Database dialect. Only postgresql is supported
DATABASE_CLIENT	—	postgresql	Database client. Only postgresql is supported

Health checks

Taco exposes two unauthenticated probe endpoints for orchestrators (Kubernetes, ECS, load balancers).

• GET /api/alive — liveness. Always returns 200 { "status": "ok" } as long as the process is serving requests. Has no dependency checks — use this for startup/liveness probes.
• GET /api/ready — readiness. Returns 200 { "status": "ok" } only when the database is reachable, the login subsystem is correctly configured, and the configured OPENID_PROVIDER can be reached (this makes a real call against the provider, obtaining a token where the provider requires one). Returns 503 { "status": "unavailable" } if any check fails. The response never includes which check failed or any error detail — that’s logged server-side only, so the probe can’t be used to fingerprint internal infrastructure.

No environment variables are needed to enable these endpoints — they check the app’s existing configuration.

Email

Variable	Required	Default	Description
EMAIL_FROM	✅	—	Sender address (e.g. Taco <noreply@example.com>)
EMAIL_SERVER	✅	—	SMTP connection string (e.g. smtps://user:pass@smtp.example.com)

OIDC / SSO login (optional)

Protect the Taco dashboard itself behind an upstream OIDC provider.

Variable	Required	Default	Description
AUTH_CLIENT_OPENID_CONFIGURATION_URL	—	—	Discovery URL of the upstream OIDC issuer
AUTH_CLIENT_ID	—	—	OIDC client ID for Taco’s own login
AUTH_CLIENT_SECRET	—	—	OIDC client secret
AUTH_CLIENT_SCOPE	—	openid profile email	Requested scopes

Provider selection

Variable	Required	Default	Description
OPENID_PROVIDER	✅	—	Provisioning backend: ory, auth0, entra, okta, keycloak, or rfc7592

Provider management API authentication

Generic credentials Taco uses to call the selected provider’s management API. Not needed for Auth0, Entra ID, Okta, or Keycloak, which use their own provider-specific variables (see below).

Variable	Required	Default	Description
OPENID_PROVIDER_AUTH_TYPE	—	—	none or client_credentials
OPENID_PROVIDER_AUTH_ISSUER	when client_credentials	—	Token endpoint issuer used to fetch admin access tokens
OPENID_PROVIDER_AUTH_CLIENT_ID	when client_credentials	—	Admin client ID
OPENID_PROVIDER_AUTH_CLIENT_SECRET	when client_credentials	—	Admin client secret
OPENID_PROVIDER_AUTH_TOKEN_METHOD	—	client_secret_post	client_secret_post or client_secret_basic
OPENID_PROVIDER_AUTH_SCOPE	—	—	Scope requested for the admin access token
OPENID_PROVIDER_AUTH_AUDIENCE	—	—	Audience requested for the admin access token

Provider-specific variables (ORY_BASE_URL, AUTH0_DOMAIN, ENTRA_*, OKTA_*, KEYCLOAK_*, RFC7592_BASE_URL) are documented on each provider’s own page — see Providers.

Statistics aggregation (Team / Business tiers)

Variable	Required	Default	Description
STATS_CRON_SECRET	✅	—	Bearer token required by POST /api/cron/aggregation
STATS_AGGREGATION_INTERVAL_MINUTES	—	1440	Business tier only — aggregation interval in minutes
STATS_WEBHOOK_SECRET	—	—	Optional — validates incoming webhook payloads to /api/events/ingest

Public API (/api/v1, Team / Business tiers)

Taco’s public API is a bearer-token resource server — it validates tokens issued by an external authorization server and never issues its own. See Public API for the full endpoint reference.

Variable	Required	Default	Description
API_AUTH_MODE	✅	—	jwt or opaque
API_AUTH_ISSUER	✅	—	Authorization server issuer URL
API_AUTH_AUDIENCE	✅	—	Expected aud claim on incoming access tokens (jwt mode)
API_AUTH_JWKS_URI	when jwt	—	JWKS endpoint used to verify token signatures
API_AUTH_INTROSPECTION_URL	when opaque	—	RFC 7662 introspection endpoint
API_AUTH_INTROSPECTION_CLIENT_ID	when opaque	—	Client ID Taco uses to authenticate to the introspection endpoint
API_AUTH_INTROSPECTION_CLIENT_SECRET	when opaque	—	Client secret for the introspection endpoint
API_AUTH_SCOPE_CLAIM	—	scope	Claim (JWT) or introspection field read as the space-delimited scope list
API_AUTH_ALLOW_INSECURE_REQUESTS	—	false	Dev only — allows API_AUTH_ISSUER/JWKS/introspection URLs to be http:// instead of https://. Not gated by NODE_ENV (which next start forces to production) — must be set explicitly.
API_DEFAULT_ORGANIZATION_ENABLED	—	false	Enables the unprefixed convenience routes (e.g. GET /api/v1/registrations) that resolve the organization from the caller’s default-organization mapping

Caution

The organization is never read from the token. Every request must either name it explicitly (/api/v1/organizations/{organizationId}/...) or rely on the default-organization mapping configured per subject in Settings → Organization → API Access.

Tip

Running locally? Use docker-compose.dev.yml combined with a provider compose file (docker-compose.hydra.yml or docker-compose.rfc7592.yml) to get a working provider without external accounts.