Skip to main content
All runtime configuration for the Factus Challenge backend is supplied through environment variables. In local development these are loaded at startup via node --env-file .env (used by the dev, test, fact, and token npm scripts). No .env.example is committed to the repository — you must create the file manually in the bc-v1/ directory before running the server.

​
.env Template

Copy the block below into bc-v1/.env and fill in every value for your environment.

​
Variable Reference

​
number
default:"4500"
The TCP port the Express server binds to. Resolved in src/main.js as process.env.PORT || 4500. In managed cloud environments (Koyeb, Render) the platform injects this automatically; you can omit it from your env var panel unless you need a specific port.
​
string
required
Base URL of the Factus API, used as the prefix for every outgoing HTTP request — for example ${process.env.url_api}/oauth/token in src/auth/token.js. No trailing slash.
​
string
required
OAuth 2.0 client ID issued by Factus. Sent in every token request body (src/auth/token.js).
​
string
required
OAuth 2.0 client secret issued by Factus. Sent alongside client_id in every token request body. Treat this like a password — never log or expose it.
​
string
required
The email address associated with your Factus account. Used as the username field in the OAuth password grant when no refresh_token is available at startup.
​
string
required
The password for your Factus account. Used alongside email in the OAuth password grant.
​
string
Optional. If this variable is present (and non-empty) when the server starts, src/auth/token.js uses the OAuth refresh_token grant instead of the password grant, skipping the need to send account credentials over the wire. After each successful token refresh the new refresh_token is written back to process.env.refresh_token automatically.
​
string
required
PostgreSQL username. For Azure Database for PostgreSQL - Flexible Server this is typically the admin username you set during instance creation.
​
string
required
Hostname (or FQDN) of the PostgreSQL server. For Azure it resembles your-server.postgres.database.azure.com. Passed directly to the pg.Pool constructor in src/database.js.
​
string
required
Name of the PostgreSQL database the application connects to.
​
string
required
Password for the PostgreSQL user identified by DB_USER.
​
boolean
required
SSL mode for the PostgreSQL connection. The value is passed directly as the ssl option of pg.Pool in src/database.js. Set to true for any cloud-hosted PostgreSQL instance (Azure, Supabase, Neon, Railway, etc.) that enforces TLS.

​
How Tokens Are Managed at Runtime

access_token is never set by the user — it lives entirely in process.env at runtime, written by the application. On every successful call to the Factus /oauth/token endpoint, src/auth/token.js writes both token values back into the running process:
The token is refreshed automatically every 55 minutes via setInterval. You only need to put refresh_token in your .env if you want to skip the initial password grant (useful in ephemeral cloud environments where the password grant is not desired).

​
Security Recommendations

Never commit your .env file. It must be listed in .gitignore. The file contains credentials that grant full access to your Factus account and PostgreSQL database.
  • Rotate client_secret regularly. Generate a fresh secret from the Factus dashboard and update it in your hosting provider’s env var panel without redeploying code.
  • Use a least-privilege PostgreSQL user. Create a dedicated database user with only the SELECT, INSERT, UPDATE, and DELETE privileges required by the application — not a superuser.
  • Always set DB_SSL=true for cloud PostgreSQL. Azure Database for PostgreSQL enforces SSL by default; connections without SSL will be rejected. The pg.Pool option in src/database.js reads this value directly.
  • Do not log environment variables. Avoid printing process.env objects in production logs — both client_secret and DB_PASSWORD would be exposed.