Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tutosrive/factus_challenge/llms.txt

Use this file to discover all available pages before exploring further.

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. 
# ── Server ──────────────────────────────────────────────────────────────────
# TCP port the Express server listens on. Defaults to 4500 if not set.
PORT=4500

# ── Factus API ───────────────────────────────────────────────────────────────
# Base URL of the Factus REST API (no trailing slash).
# Sandbox:    https://api-sandbox.factus.com.co
# Production: https://api.factus.com.co
url_api=https://api-sandbox.factus.com.co

# OAuth 2.0 credentials — obtain from your Factus account dashboard.
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

# Factus account credentials — used for the OAuth password grant on first run.
email[email protected]
password=your_factus_password

# Optional. If present on startup, the server uses a refresh_token grant
# instead of the password grant, saving one round-trip.
# refresh_token=OPTIONAL_REFRESH_TOKEN

# ── PostgreSQL (Azure) ───────────────────────────────────────────────────────
DB_USER=your_pg_user
DB_HOST=your-server.postgres.database.azure.com
DB_NAME=your_database_name
DB_PASSWORD=your_pg_password

# Set to true for all cloud PostgreSQL instances that enforce SSL (e.g. Azure).
DB_SSL=true

​
Variable Reference

​
PORT
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.
​
url_api
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.
ModeValue
Sandboxhttps://api-sandbox.factus.com.co
Productionhttps://api.factus.com.co
​
client_id
string
required
OAuth 2.0 client ID issued by Factus. Sent in every token request body (src/auth/token.js).
​
client_secret
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.
​
email
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.
​
password
string
required
The password for your Factus account. Used alongside email in the OAuth password grant.
​
refresh_token
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.
​
DB_USER
string
required
PostgreSQL username. For Azure Database for PostgreSQL - Flexible Server this is typically the admin username you set during instance creation.
​
DB_HOST
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.
​
DB_NAME
string
required
Name of the PostgreSQL database the application connects to.
​
DB_PASSWORD
string
required
Password for the PostgreSQL user identified by DB_USER.
​
DB_SSL
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:
process.env.refresh_token = res.data.refresh_token;
process.env.access_token  = res.data.access_token;
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us