Environment Variables

Complete reference for all environment variables used by the Vertical Template.

Quick Setup

Copy the example file and fill in your values:

cp .env.example .env.local

Required Variables

Authentication (Microsoft Entra ID)

Variable	Description	Example
ENTRA_TENANT_ID	Your Entra tenant GUID	12345678-1234-...
ENTRA_TENANT_NAME	Your Entra tenant name	yourcompany.onmicrosoft.com
ENTRA_CLIENT_ID	App registration client ID	abcdef12-3456-...
ENTRA_CLIENT_SECRET	App registration secret	abc~xyz...
ENTRA_SCOPES	OAuth scopes	openid profile email

# .env.local
ENTRA_TENANT_ID=12345678-1234-1234-1234-123456789012
ENTRA_TENANT_NAME=yourcompany.onmicrosoft.com
ENTRA_CLIENT_ID=abcdef12-3456-7890-abcd-ef1234567890
ENTRA_CLIENT_SECRET=abc~YourSecretHere
ENTRA_SCOPES=openid profile email

NextAuth Configuration

Variable	Description	Example
NEXTAUTH_SECRET	JWT signing secret	Generated secret
NEXTAUTH_URL	Application URL	http://localhost:3000

# Generate a secure secret
openssl rand -base64 32

# .env.local
NEXTAUTH_SECRET=your-generated-secret-here
NEXTAUTH_URL=http://localhost:3000

Optional Variables

Tenant Configuration

Variable	Description	Default
TENANT_DEFAULT_ID	Default tenant ID	template
WORKFLOW_DEFAULT_ID	Default workflow ID	-

TENANT_DEFAULT_ID=my-tenant
WORKFLOW_DEFAULT_ID=default-workflow

API Configuration

Variable	Description	Example
BASE_URL_PUBLIC_API	Backend API URL	https://api.example.com

BASE_URL_PUBLIC_API=https://api.example.com

Feature Flags

Variable	Description	Default
NEXT_PUBLIC_ENABLE_CHAT	Enable chat feature	false
NEXT_PUBLIC_ENABLE_AI	Enable AI features	false

NEXT_PUBLIC_ENABLE_CHAT=true
NEXT_PUBLIC_ENABLE_AI=true

Runtime Configuration

Some configuration is delivered at runtime via the /api/eai/config endpoint rather than environment variables. This keeps secrets out of the client bundle.

// RuntimeConfig type
interface RuntimeConfig {
  tenants: Record<string, {
    tenantId?: string;
    workflowId?: string;
  }>;
  mapboxToken?: string;
}

Access in components:

import { useRuntimeConfig } from '@enterpriseaigroup/client';

function MyComponent() {
  const { mapboxToken } = useRuntimeConfig();
  // ...
}

Environment-Specific Files

File	Purpose	Git
.env.example	Template for developers	Committed
.env.local	Local development	Ignored
.env.development	Development overrides	Optional
.env.production	Production values	In CI/CD

Variable Naming Conventions

Prefix	Availability	Use Case
NEXT_PUBLIC_*	Client + Server	Public feature flags
ENTRA_*	Server only	Authentication
*_SECRET	Server only	Sensitive values
No prefix	Server only	General config

Entra ID App Registration

To get the authentication variables, you need an Entra ID app registration:

1. Go to Azure Portal → Entra ID → App registrations
2. Create a new registration or use existing
3. Configure:
   • Redirect URI: http://localhost:3000/api/auth/callback/azure-ad
   • Platform: Web
   • API permissions: openid, profile, email
4. Create a client secret (Certificates & secrets)
5. Copy values to .env.local

Example Complete .env.local

# Authentication (Microsoft Entra ID)
ENTRA_TENANT_ID=12345678-1234-1234-1234-123456789012
ENTRA_TENANT_NAME=yourcompany.onmicrosoft.com
ENTRA_CLIENT_ID=abcdef12-3456-7890-abcd-ef1234567890
ENTRA_CLIENT_SECRET=abc~YourSecretHere
ENTRA_SCOPES=openid profile email

# NextAuth
NEXTAUTH_SECRET=your-32-character-secret-here
NEXTAUTH_URL=http://localhost:3000

# API
BASE_URL_PUBLIC_API=https://api.example.com

# Tenant
TENANT_DEFAULT_ID=my-tenant
WORKFLOW_DEFAULT_ID=default-workflow

# Features
NEXT_PUBLIC_ENABLE_CHAT=true
NEXT_PUBLIC_ENABLE_AI=false

Troubleshooting

"Invalid client secret"

• Secrets expire - check expiration date in Azure Portal
• Ensure no trailing whitespace in .env.local
• Restart dev server after changes

"Invalid redirect URI"

• Verify redirect URI matches exactly in Entra registration
• Include port number: http://localhost:3000/api/auth/callback/azure-ad

Environment variables not loading

• File must be named .env.local (not .env)
• Restart the development server
• Check for syntax errors (no quotes needed)

Related Documentation

• Quickstart - Initial setup
• Authentication ADR - Auth architecture