Environment Variables — Cognest.ai Docs

Core Variables#

These variables are required for every Cognest project.

Variable	Required	Description
COGNEST_API_KEY	Yes	Your Cognest API key (starts with cn_live_ or cn_test_)
COGNEST_ORG_ID	Yes	Organization identifier from your dashboard
COGNEST_ENV	No	Environment name: development, staging, production (default: development)
COGNEST_LOG_LEVEL	No	Logging level: debug, info, warn, error (default: info)
COGNEST_PORT	No	Server port (default: 3000)

Loading Order#

Cognest loads environment variables in the following priority (highest to lowest):

Shell environment variables (already exported)
.env.local — Local overrides (gitignored)
.env.{environment} — Environment-specific (e.g., .env.production)
.env — Default values

.env.local

# .env — Default values (committed to git)
COGNEST_ENV=development
COGNEST_PORT=3000
COGNEST_LOG_LEVEL=info

# .env.local — Secrets (gitignored)
COGNEST_API_KEY=cn_test_sk_a1b2c3d4e5f6...
COGNEST_ORG_ID=org_my-team

# Integration credentials
WHATSAPP_PHONE_ID=1234567890
WHATSAPP_ACCESS_TOKEN=EAAx...
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=abc123...

Integration Variables#

Each integration has its own set of required environment variables. Here are the most common ones:

Messaging Integrations#

Variable	Integration	Description
WHATSAPP_PHONE_ID	WhatsApp	Business phone number ID from Meta dashboard
WHATSAPP_ACCESS_TOKEN	WhatsApp	Permanent access token from Meta
WEBHOOK_VERIFY_TOKEN	WhatsApp	Custom string for webhook verification
TELEGRAM_BOT_TOKEN	Telegram	Bot token from @BotFather
SLACK_BOT_TOKEN	Slack	Bot user OAuth token (xoxb-...)
SLACK_SIGNING_SECRET	Slack	Request signing secret from Slack app settings
DISCORD_BOT_TOKEN	Discord	Bot token from Discord developer portal
DISCORD_APPLICATION_ID	Discord	Application ID for slash commands

Google Integrations#

Variable	Integration	Description
GMAIL_CLIENT_ID	Gmail	OAuth 2.0 client ID from Google Cloud Console
GMAIL_CLIENT_SECRET	Gmail	OAuth 2.0 client secret
GOOGLE_CALENDAR_CLIENT_ID	Google Calendar	OAuth 2.0 client ID
GOOGLE_CALENDAR_CLIENT_SECRET	Google Calendar	OAuth 2.0 client secret
GOOGLE_DRIVE_CLIENT_ID	Google Drive	OAuth 2.0 client ID
GOOGLE_DRIVE_CLIENT_SECRET	Google Drive	OAuth 2.0 client secret

Other Integrations#

Variable	Integration	Description
NOTION_API_KEY	Notion	Internal integration token from Notion
GITHUB_TOKEN	GitHub	Personal access token or GitHub App token
TWITTER_API_KEY	Twitter / X	API key from Twitter developer portal
TWITTER_API_SECRET	Twitter / X	API secret key
TWITTER_ACCESS_TOKEN	Twitter / X	User access token
TWITTER_ACCESS_SECRET	Twitter / X	User access token secret
LINKEDIN_CLIENT_ID	LinkedIn	OAuth 2.0 client ID
LINKEDIN_CLIENT_SECRET	LinkedIn	OAuth 2.0 client secret
STRIPE_SECRET_KEY	Stripe	Secret key (starts with sk_live_ or sk_test_)
STRIPE_WEBHOOK_SECRET	Stripe	Webhook endpoint signing secret

Production Secrets Management#

In production, we recommend using a secrets manager instead of .env files. Cognest supports native integration with popular secret stores:

cognest.config.yaml

# cognest.config.yaml
secrets:
  provider: aws-ssm          # aws-ssm | vault | gcp-secrets | azure-keyvault
  prefix: /cognest/prod/    # Key prefix in the secrets store
  cache_ttl: 300             # Cache secrets for 5 minutes

When using a secrets provider, environment variables referenced in your config (${VAR_NAME}) are first looked up in the secrets store, then fall back to process.env.