API Key Management

Introduction

API Key Management in the AI for Thai EMS project centers around a single, critical credential: the Google Gemini API key. This key is essential for all interactions with the Google AI services, which power the core features of the application, including emergency call transcript analysis and the interactive AI chatbot.

The management strategy is designed for a client-side web application built with Vite. It involves using environment variables for local development and a build-time replacement mechanism to securely inject the key into the application code. This ensures that the API key is not hardcoded or exposed in the version-controlled source code.

Configuration and Loading

The process of configuring and loading the Gemini API key is handled through environment variables and the Vite build tool.

Local Development Setup

For local development, the API key must be placed in a .env.local file at the root of the project. This file is not tracked by Git. The key is assigned to the GEMINI_API_KEY variable.

Sources: README.md:13

Build-Time Injection

The Vite configuration is responsible for making the API key from the environment variable available within the application's code. It uses Vite's define feature to perform a global search-and-replace at build time.

The configuration loads the GEMINI_API_KEY from the environment and maps it to two global variables: process.env.API_KEY and process.env.GEMINI_API_KEY. This provides flexibility, as different parts of the code use slightly different variable names (process.env.API_KEY is used in the services).

Sources: vite.config.ts:5-14

The following diagram illustrates the API key loading flow from the environment file to the final application bundle.

The key configuration from vite.config.ts is shown below:

// vite.config.ts
export default defineConfig(({ mode }) => {
    const env = loadEnv(mode, '.', '');
    return {
      // ...
      define: {
        'process.env.API_KEY': JSON.stringify(env.GEMINI_API_KEY),
        'process.env.GEMINI_API_KEY': JSON.stringify(env.GEMINI_API_KEY)
      },
      // ...
    };
});

Sources: vite.config.ts:4-15

Service Initialization

The API key is used to initialize the Google GenAI client, which is the gateway to the Gemini API.

geminiService.ts

The primary service, geminiService.ts, creates a singleton instance of the GoogleGenAI client. This instance is then used for making API calls, such as analyzing emergency transcripts and handling chat messages. The service reads the key from process.env.API_KEY.

// services/geminiService.ts
import { GoogleGenAI, Type, GenerateContentResponse } from "@google/genai";
import { AiAnalysisResult } from '../types';

// We assume process.env.API_KEY is available in the execution environment.
const ai = new GoogleGenAI({ apiKey: process.env.API_KEY! });

Sources: services/geminiService.ts:4-5

Direct Instantiation in Components

In some cases, a new GoogleGenAI client is instantiated directly within a component. The Chatbot component does this to connect to the live audio transcription service, demonstrating that the API key is accessible throughout the application's scope where needed.

// components/Chatbot.tsx
try {
  const ai = new GoogleGenAI({ apiKey: process.env.API_KEY! });
  const session = await ai.live.connect({
    // ... session config
  });
  // ...
} catch (e) {
  // ...
}

Sources: components/Chatbot.tsx:126-132

Usage and Error Handling

The configured API key is implicitly used whenever a component calls a function from geminiService.ts or instantiates its own client.

The following sequence diagram shows the typical flow when the AiDemo component requests a transcript analysis.

If the API call fails, for example due to a missing or invalid API key, the application provides feedback to the user. The AiDemo component catches errors from the service and displays a message prompting the user to check their API key configuration.

Sources: components/AiDemo.tsx:51-53

Summary

The project employs a straightforward and secure method for managing the Gemini API key. By leveraging Vite's environment variable and define features, the key is safely injected at build time, avoiding exposure in the source repository. The key is made available as process.env.API_KEY and is used to instantiate GoogleGenAI clients in both a centralized service (geminiService.ts) and directly in components (Chatbot.tsx) for specialized features. Proper error handling is in place to guide developers in case of configuration issues.