# **Migration to Workspace-Level API Key Management**
**Created at** 2025-10-07
**Created by** Manoj Vala

## **Executive Summary**
Migrate from direct API key input per agent to centralized workspace-level key management with zero downtime and backward compatibility.

---

## **1. Current System**
- Agents have direct input fields for:
- `tts_key` (string)
- `stt_key` (string)
- `elevenlabs_key` (string)
- Keys are stored in plain text on agent records
- Visible/editable by all users with agent access

## **2. Target System**
- **Admin Module:** Create and manage API Key Resources with:
- Unique Name (e.g., "Production-TTS-Primary")
- Key Type (TTS/STT/ElevenLabs)
- Encrypted Key Value
- Assigned Workspace(s)
- **User Side:** Dropdowns replacing direct input fields
- Agents store references (`selected_tts_key_id`) instead of raw keys

---

## **3. Migration Phases**

### **PHASE 1: Backend Expansion & Audit**
**Goal:** Deploy admin features without affecting users

**Tasks:**
1. **Database Changes**
- Create `api_key_resources` table
- Keep existing `tts_key`, `stt_key`, `elevenlabs_key` columns

2. **Admin Panel Development**
- CRUD interface for API Key Resources
- Workspace assignment functionality
- Key validation for new resources

3. **Data Audit & Preparation**
- Generate Excel report: `Workspace -> Agents -> Distinct API Keys`
- Manually create Key Resources with meaningful names
- Assign relevant keys to each workspace

**Outcome:**
- Admins can manage keys
- Users unaffected - agents work with old keys
- System ready for frontend switch

---

### **PHASE 2: Frontend Deployment & Data Migration**
**Goal:** Switch UI to dropdowns and migrate existing data

**Tasks:**
1. **Backend Service Updates**
- Implement key resolution logic:

2. **Frontend Changes**
- Replace text inputs with dropdowns in agent form
- Populate dropdowns via `/workspaces/:id/api-keys` endpoint
- Submit `selected_xxx_key_id` instead of raw keys

3. **Data Migration Strategy**
- **Option A (Gradual):** Auto-migrate when users edit agents
- If key is actual key then use as it is.
- Else the key has UUID then it will automatically get the actual API Key from central key management.
- **Option B (Bulk):** Run migration script to make UUID based on associated keys.

**Outcome:**
- Users select keys from dropdowns
- Existing agents automatically work via fallback
- Gradual migration to new system

---

## **Risk Mitigation & Rollback Plan**

### **Rollback Procedure:**
1. **Revert Frontend:** Restore text input fields
2. **Revert Backend:** Service layer uses old key fields directly
3. **Data Integrity:** Old keys remain intact throughout process

### **Validation Checks:**
- All workspace keys audited and created in Phase 1
- Migration script tested on staging environment
- Fallback logic verified for all key types
- Admin can create/modify keys without breaking agents

---

flowchart TD
    subgraph A [Phase 1: Backend/Frontend Expansion & Audit]
        A1[Database: Create api_key_resources table] --> A2
        A2[Admin Panel: CRUD for Key Resources] --> A3
        A3[Export Excel Audit: Workspace -> Agents -> Keys] --> A4
        A4[Manual Analysis & Key Creation] --> A5
        A5[Assign Keys to Workspaces]
    end

    subgraph B [Phase 2: Backend/Frontend & Migration]
        B1[Update Backend Services<br/>with Fallback Logic] --> B2
        B2[Deploy New UI with Dropdowns] --> B3
        
        B3{Migration Approach}
        B3 --> B5[Bulk: Run migration script]
    end

    subgraph C [Phase 3: Cleanup - Optional]
        C1[Monitor old key field usage] --> C2
        C2[Drop old key columns] --> C3[Archive artifacts]
    end

    subgraph D [Data Flow - Post Migration]
        D1[User selects from dropdown] --> D2[Agent stores key_id reference]
        D2 --> D3[Service resolves actual key]
        D3 --> D4[API calls work as before]
    end

    A --> B
    B --> C
    B --> D

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0