Session Keys

Environment variables, API endpoints, localStorage keys, and external service configuration constants used throughout the WorkPayCore frontend application.

Overview

The session keys constants centralize all configuration values, API endpoints, environment variables, and external service tokens to ensure consistent access to system resources and maintain separation between development, staging, and production environments.

API Endpoints

Base API Endpoints

Core API endpoint configurations for different API versions.

export const BASE_API_V1_ENDPOINT = import.meta.env.VITE_API_HOST_V1;
export const BASE_API_V2_ENDPOINT = import.meta.env.VITE_API_HOST_V2;
export const BASE_API_V3_ENDPOINT = import.meta.env.VITE_API_HOST_V3;
export const LEGACY_HOST_ADDRESS = import.meta.env.VITE_LEGACY_HOST_ADDRESS;

Environment Variables:

VITE_API_HOST_V1: Version 1 API endpoint
VITE_API_HOST_V2: Version 2 API endpoint (primary)
VITE_API_HOST_V3: Version 3 API endpoint (modern)
VITE_LEGACY_HOST_ADDRESS: Legacy API support

Application Addresses

External application and service endpoints.

export const RECRUITMENT_APP_ADDRESS = import.meta.env
  .VITE_RECRUITMENT_APP_ADDRESS;
export const PERFORMANCE_APP_ADDRESS = import.meta.env
  .VITE_PERFORMANCE_APP_ADDRESS;
export const { VITE_MAIN_APP_ADDRESS, MODE } = import.meta.env;
export const HOST_ADDRESS = import.meta.env.VITE_HOST_ADDRESS;

Use Cases:

Cross-application navigation
Service integration
Environment-specific routing

Authentication & Authorization Keys

Core Authentication

localStorage keys for authentication and authorization data.

export const AUTH_COMPANY_ID = 'AUTH_COMPANY_ID';
export const AUTHORIZE_FOR = 'AUTHORIZE_FOR';
export const AUTH_SWITCHED_COMPANY_ID_KEY = 'AUTH_SWITCHED_COMPANY_ID_KEY';
export const AUTH_HEAD_OFFICE_ID_KEY = 'AUTH_HEAD_OFFICE_ID_KEY';
export const AUTH_ROLE_KEY = 'AUTH_ROLE_KEY';
export const AUTH_FEATURES_KEY = 'AUTH_FEATURES_KEY';
export const IS_ONBOARDING_KEY = 'IS_ONBOARDING_KEY';

Key Purposes:

AUTH_COMPANY_ID: Current user's company identification
AUTHORIZE_FOR: Authorization scope and permissions
AUTH_SWITCHED_COMPANY_ID_KEY: Company switching functionality
AUTH_HEAD_OFFICE_ID_KEY: Head office identification
AUTH_ROLE_KEY: User role and permissions
AUTH_FEATURES_KEY: Available features for the user
IS_ONBOARDING_KEY: Onboarding state tracking

Security & Encryption

Cryptographic Configuration

export const CRYPTO_KEY = import.meta.env.VITE_CRYPTO_SECRET_KEY;

Security Note: Used for client-side encryption operations and should be handled with appropriate security measures.

External Service Integrations

Analytics & Tracking

export const SEGMENT_KEY = import.meta.env.VITE_SEGMENT_KEY;
export const USERPILOT_TOKEN = import.meta.env.VITE_USERPILOT_TOKEN;
export const INTERCOM_TOKEN = import.meta.env.VITE_INTERCOM_TOKEN;

Services:

Segment: Analytics and event tracking
Userpilot: User onboarding and guidance
Intercom: Customer support and messaging

Error Tracking

export const SENTRY_DNS = import.meta.env.VITE_SENTRY_DNS_DISABLED;
export const SENTRY_TRACE_SAMPLE_RATE = import.meta.env
  .VITE_SENTRY_TRACE_SAMPLE_RATE;

Sentry Configuration:

Error monitoring and performance tracking
Configurable sampling rates for performance monitoring

Payment Processing

export const PAYSTACK_PUB_KEY = import.meta.env.VITE_PAYSTACK_PUB_KEY;

Payment Integration:

Paystack public key for payment processing
Used for secure payment form initialization

Feature Management

export const HEADWAY_ACCOUNT_ID = import.meta.env.VITE_HEADWAY_ACCOUNT_ID;
export const CHECKSUM_ACCOUNT_ID = import.meta.env.VITE_CHECKSUM_ACCOUNT_ID;

Third-Party Services:

Feature announcement and changelog management
Account verification and security checks

Environment Configuration

Environment Detection

export const ACTUAL_PROD = import.meta.env.VITE_ACTUAL_PROD;
export const { MODE } = import.meta.env;

Environment Values:

ACTUAL_PROD: Production environment flag
MODE: Vite environment mode (development, production, etc.)

External Resources & Documentation

Documentation Links

export const TAX_COMPLIANCE_DOC_LINK =
  'https://drive.google.com/file/d/1irBRnZ4RImfQ-OQab3pmajF1v4J7O5h2/view';

export const NSSF_NO_PAYMENT_DOC_LINK =
  'https://drive.google.com/file/d/1I2gh6RqugY8H7IcdJi2_GotfeHGS2nEd/view';

export const HOUSING_LEVY_DOC_LINK =
  'https://drive.google.com/file/d/1pE3H5VI9wFfjn_JKQVqh-nAjwVpT-9sd/view';

export const NSSF_PAYMENT_GUIDE_DOC_LINK =
  'https://docs.google.com/document/d/1jKr-eu8iRaWDBIuABx5Bs-kT_B3fnt3IiIyPeXSYKIw/view';

export const HOUSING_LEVY_GUIDE_LINK =
  'https://learn.myworkpay.com/knowledge/housing-levy-relief';

External Forms & Services

export const INSURANCE_FORM_LINK =
  'https://docs.google.com/forms/d/e/1FAIpQLSexVEBRCUmqt_g18FyuwnsOie93dq2G8806q76cKK3Mb2q8WQ/viewform';

export const TWO_FA_LINK =
  'https://docs.google.com/document/d/19hwX6UEYThTiuX8G1mIc7PNmwS6C3MUuCIz2qsvu9Cw/edit?usp=sharing';

export const EWA_BANNER_FORM =
  'https://share.hsforms.com/1bpRKvhkDSZefyf364tn6NQ3uu56';

export const FS_PAGE = 'https://www.myworkpay.com/financial-services';

Terms & Conditions

export const MY_WALLET_TnC =
  'https://docs.google.com/document/d/1_X7yZLfnHzoW8GhjrE3X3GI5b7YEQbCFX_Oc6YQJjOA/view';

export const MY_WALLET_PRIVACY_POLICY =
  'https://www.myworkpay.com/financial-services';

export const LOANS_TERM_AND_CONDITIONS =
  'https://drive.google.com/file/d/17npp1SUEFZdvDu26CZ-JucmCEQxvb_Gt/view?usp=sharing';

Special Features

export const INSURANCE_URL = import.meta.env.VITE_INSURANCE_URL;
export const MBAYA_NET_PAY_REPORT = import.meta.env.VITE_MBAYA_NET_PAY_REPORT;

Usage Examples

Environment-Based Configuration

import {
  BASE_API_V2_ENDPOINT,
  MODE,
  ACTUAL_PROD,
} from '@/utils/constants/session-keys';

const getAPIConfig = () => {
  const isDevelopment = MODE === 'development';
  const isProduction = ACTUAL_PROD === 'true';

  return {
    baseURL: BASE_API_V2_ENDPOINT,
    timeout: isDevelopment ? 30000 : 10000,
    retries: isProduction ? 3 : 1,
    debug: isDevelopment,
  };
};

Authentication State Management

import {
  AUTH_COMPANY_ID,
  AUTH_ROLE_KEY,
  AUTH_FEATURES_KEY,
} from '@/utils/constants/session-keys';

const useAuthState = () => {
  const getStoredAuthData = () => {
    return {
      companyId: localStorage.getItem(AUTH_COMPANY_ID),
      userRole: JSON.parse(localStorage.getItem(AUTH_ROLE_KEY) || '{}'),
      features: JSON.parse(localStorage.getItem(AUTH_FEATURES_KEY) || '[]'),
    };
  };

  const clearAuthData = () => {
    localStorage.removeItem(AUTH_COMPANY_ID);
    localStorage.removeItem(AUTH_ROLE_KEY);
    localStorage.removeItem(AUTH_FEATURES_KEY);
  };

  return { getStoredAuthData, clearAuthData };
};

External Service Integration

import {
  SEGMENT_KEY,
  USERPILOT_TOKEN,
  INTERCOM_TOKEN,
} from '@/utils/constants/session-keys';

const initializeExternalServices = () => {
  // Initialize Segment analytics
  if (SEGMENT_KEY) {
    analytics.load(SEGMENT_KEY);
  }

  // Initialize Userpilot
  if (USERPILOT_TOKEN) {
    userpilot.load(USERPILOT_TOKEN);
  }

  // Initialize Intercom
  if (INTERCOM_TOKEN) {
    window.Intercom('boot', { app_id: INTERCOM_TOKEN });
  }
};

Payment Integration

import { PAYSTACK_PUB_KEY } from '@/utils/constants/session-keys';

const initializePaystack = () => {
  if (!PAYSTACK_PUB_KEY) {
    throw new Error('Paystack public key not configured');
  }

  const script = document.createElement('script');
  script.src = 'https://js.paystack.co/v1/inline.js';
  script.onload = () => {
    // Paystack loaded and ready to use
    console.log('Paystack initialized with key:', PAYSTACK_PUB_KEY);
  };
  document.head.appendChild(script);
};

Company Switching

import {
  AUTH_COMPANY_ID,
  AUTH_SWITCHED_COMPANY_ID_KEY,
} from '@/utils/constants/session-keys';

const useCompanySwitching = () => {
  const switchCompany = (newCompanyId: string) => {
    // Store current company for switching back
    const currentCompany = localStorage.getItem(AUTH_COMPANY_ID);
    localStorage.setItem(AUTH_SWITCHED_COMPANY_ID_KEY, currentCompany || '');

    // Switch to new company
    localStorage.setItem(AUTH_COMPANY_ID, newCompanyId);

    // Reload to apply changes
    window.location.reload();
  };

  const revertCompany = () => {
    const originalCompany = localStorage.getItem(AUTH_SWITCHED_COMPANY_ID_KEY);
    if (originalCompany) {
      localStorage.setItem(AUTH_COMPANY_ID, originalCompany);
      localStorage.removeItem(AUTH_SWITCHED_COMPANY_ID_KEY);
      window.location.reload();
    }
  };

  return { switchCompany, revertCompany };
};

Documentation Links Helper

import {
  TAX_COMPLIANCE_DOC_LINK,
  NSSF_PAYMENT_GUIDE_DOC_LINK,
  HOUSING_LEVY_GUIDE_LINK,
} from '@/utils/constants/session-keys';

const getHelpDocumentLink = (type: string) => {
  const docLinks = {
    tax: TAX_COMPLIANCE_DOC_LINK,
    nssf: NSSF_PAYMENT_GUIDE_DOC_LINK,
    housing: HOUSING_LEVY_GUIDE_LINK,
  };

  return docLinks[type] || null;
};

const openHelpDocument = (type: string) => {
  const link = getHelpDocumentLink(type);
  if (link) {
    window.open(link, '_blank', 'noopener,noreferrer');
  }
};

Environment Variable Setup

Development Environment (.env.development)

# API Endpoints
VITE_API_HOST_V1=https://dev-api.workpay.co.ke/api/v1
VITE_API_HOST_V2=https://dev-api.workpay.co.ke/api/v2
VITE_API_HOST_V3=https://dev-api.workpay.co.ke/api/v3

# External Services
VITE_SEGMENT_KEY=dev_segment_key
VITE_USERPILOT_TOKEN=dev_userpilot_token
VITE_INTERCOM_TOKEN=dev_intercom_token

# Payment
VITE_PAYSTACK_PUB_KEY=pk_test_xxx

# Environment
VITE_ACTUAL_PROD=false

Production Environment (.env.production)

# API Endpoints
VITE_API_HOST_V1=https://api.workpay.co.ke/api/v1
VITE_API_HOST_V2=https://api.workpay.co.ke/api/v2
VITE_API_HOST_V3=https://api.workpay.co.ke/api/v3

# External Services
VITE_SEGMENT_KEY=prod_segment_key
VITE_USERPILOT_TOKEN=prod_userpilot_token
VITE_INTERCOM_TOKEN=prod_intercom_token

# Payment
VITE_PAYSTACK_PUB_KEY=pk_live_xxx

# Environment
VITE_ACTUAL_PROD=true

Security Best Practices

Sensitive Data Handling

// ✅ Good: Environment variable usage
const apiKey = import.meta.env.VITE_API_KEY;

// ❌ Bad: Hardcoded sensitive data
const apiKey = 'hard-coded-key-123';

Runtime Environment Checks

import { ACTUAL_PROD, MODE } from '@/utils/constants/session-keys';

const isProductionEnvironment = () => {
  return ACTUAL_PROD === 'true' && MODE === 'production';
};

const isDevelopmentEnvironment = () => {
  return MODE === 'development';
};

Secure localStorage Operations

import { AUTH_COMPANY_ID } from '@/utils/constants/session-keys';

const secureLocalStorageSet = (key: string, value: string) => {
  try {
    if (typeof Storage !== 'undefined') {
      localStorage.setItem(key, value);
    }
  } catch (error) {
    console.error('localStorage not available:', error);
  }
};

const secureLocalStorageGet = (key: string): string | null => {
  try {
    if (typeof Storage !== 'undefined') {
      return localStorage.getItem(key);
    }
  } catch (error) {
    console.error('localStorage not available:', error);
  }
  return null;
};

Testing & Development

Mock Environment Setup

// For testing environments
const mockSessionKeys = {
  BASE_API_V2_ENDPOINT: 'http://localhost:3001/api/v2',
  SEGMENT_KEY: 'test_segment_key',
  PAYSTACK_PUB_KEY: 'pk_test_mock',
};

const getSessionKey = (key: string) => {
  if (process.env.NODE_ENV === 'test') {
    return mockSessionKeys[key] || import.meta.env[`VITE_${key}`];
  }
  return import.meta.env[`VITE_${key}`];
};

General Helpers - For localStorage operations
Browser Utils - For environment detection
EOR Helpers - For EOR portal configuration

TypeScript Definitions

// Environment variable types
interface EnvironmentConfig {
  BASE_API_V1_ENDPOINT: string;
  BASE_API_V2_ENDPOINT: string;
  BASE_API_V3_ENDPOINT: string;
  LEGACY_HOST_ADDRESS: string;
  RECRUITMENT_APP_ADDRESS: string;
  PERFORMANCE_APP_ADDRESS: string;
  VITE_MAIN_APP_ADDRESS: string;
  HOST_ADDRESS: string;
  CRYPTO_KEY: string;
  SEGMENT_KEY: string;
  USERPILOT_TOKEN: string;
  INTERCOM_TOKEN: string;
  PAYSTACK_PUB_KEY: string;
  ACTUAL_PROD: string;
  MODE: string;
}

// localStorage key types
type AuthStorageKeys =
  | 'AUTH_COMPANY_ID'
  | 'AUTHORIZE_FOR'
  | 'AUTH_SWITCHED_COMPANY_ID_KEY'
  | 'AUTH_HEAD_OFFICE_ID_KEY'
  | 'AUTH_ROLE_KEY'
  | 'AUTH_FEATURES_KEY'
  | 'IS_ONBOARDING_KEY';

export const AUTH_COMPANY_ID: AuthStorageKeys;
export const AUTHORIZE_FOR: AuthStorageKeys;
// ... other exports

Migration & Maintenance

Environment Variable Migration

When adding new environment variables:

Add to all environment files (development, staging, production)
Update TypeScript definitions for type safety
Add validation to ensure required variables are present
Update documentation with usage examples
Test across environments to ensure consistency

Deprecation Process

When deprecating session keys:

Mark as deprecated in code comments
Provide migration path to new keys
Log warnings when deprecated keys are used
Remove after grace period (typically 2-3 releases)

These session key constants provide centralized configuration management for the WorkPayCore frontend application, ensuring secure and consistent access to environment-specific resources and external services.

Overview​

API Endpoints​

Base API Endpoints​

Application Addresses​

Authentication & Authorization Keys​

Core Authentication​

Security & Encryption​

Cryptographic Configuration​

External Service Integrations​

Analytics & Tracking​

Error Tracking​

Payment Processing​

Feature Management​

Environment Configuration​

Environment Detection​

External Resources & Documentation​

Documentation Links​

External Forms & Services​

Terms & Conditions​

Special Features​

Usage Examples​

Environment-Based Configuration​

Authentication State Management​

External Service Integration​

Payment Integration​

Company Switching​

Documentation Links Helper​

Environment Variable Setup​

Development Environment (.env.development)​

Production Environment (.env.production)​

Security Best Practices​

Sensitive Data Handling​

Runtime Environment Checks​

Secure localStorage Operations​

Testing & Development​

Mock Environment Setup​

Related Utilities​

TypeScript Definitions​

Migration & Maintenance​

Environment Variable Migration​

Deprecation Process​