AI API Keys

The AI API Keys endpoints allow you to create and manage repository-specific API keys for AI-powered features. These keys provide secure, scoped authentication for AI operations within individual repositories.

Overview

AI API Keys are specialized authentication credentials that enable AI-powered features and services for specific repositories. Unlike workspace-level AI LLM configurations, these keys are repository-scoped and designed for service-to-service authentication.

Key Characteristics

• Repository-Scoped: Each API key is tied to a single repository

• AI Provider Specific: Keys are associated with specific AI providers (OpenAI, Google, Anthropic, etc.)

• Secure Generation: Keys and secrets are cryptographically generated

• One-Time Secret Display: Secrets are only shown during creation

• Soft Delete: Deleted keys maintain audit history

• Access Controlled: Respects repository-level permissions

Supported AI Providers

• OPENAI - OpenAI (GPT-4, GPT-3.5, etc.)

• GOOGLE - Google AI (Gemini, PaLM, etc.)

• ANTHROPIC - Anthropic (Claude models)

• AWS - Amazon Bedrock and AWS AI services

• OTHER - Custom or additional AI provider endpoints

Available Endpoints

Key Management

• POST /repo/{repoId}/ai/apikey - Create a new AI API key for a repository

• GET /repo/{repoId}/ai/apikey - List all AI API keys for a repository

• PUT /repo/{repoId}/ai/apikey/{apikeyId} - Update an AI API key's properties

• DELETE /repo/{repoId}/ai/apikey/{apikeyId} - Delete an AI API key

Common Use Cases

1. Creating an AI API Key for a Repository

// Create an AI API key for OpenAI integration
const response = await client.createRepoAiApiKey("repo-123", {
  name: "Production OpenAI Key",
  aiType: "OPENAI"
});

console.log(`Key: ${response.key}`);
console.log(`Secret: ${response.secret}`); // Only shown once!

// Store the secret securely - it won't be shown again
process.env.AI_SECRET = response.secret;

2. Listing Repository API Keys

// Get all AI API keys for a repository
const response = await client.getRepoAiApiKeys("repo-123");

response.apiKeys.forEach(key => {
  console.log(`${key.name} (${key.aiType}): ${key.key}`);
  console.log(`Created: ${key.createdAt}`);
  console.log(`Status: ${key.deletedAt ? 'Deleted' : 'Active'}`);
});

3. Updating an API Key

// Update the name of an API key
await client.updateRepoAiApiKey(
  "repo-123",
  "apikey-456",
  {
    name: "Updated Production Key"
  }
);

4. Rotating API Keys

// Best practice: Create new key before deleting old one
const newKey = await client.createRepoAiApiKey("repo-123", {
  name: "New Production Key",
  aiType: "OPENAI"
});

// Update your services to use the new key
await updateServiceConfiguration(newKey.key, newKey.secret);

// After confirming new key works, delete the old one
await client.deleteRepoAiApiKey("repo-123", "old-apikey-id");

Security Best Practices

1. Secret Management

Critical: The API secret is only returned once during creation. Store it securely immediately.

const response = await client.createRepoAiApiKey("repo-123", {
  name: "My AI Key",
  aiType: "OPENAI"
});

// ✅ GOOD: Store in secure secrets manager
await secretsManager.store('ai-api-secret', response.secret);

// ❌ BAD: Log or display in plain text
console.log(response.secret); // Never do this!

2. Key Rotation

Regularly rotate API keys to maintain security:

1. Create a new API key

2. Update services to use the new key

3. Verify the new key works correctly

4. Delete the old key

5. Update documentation with the new key ID

3. Access Control

• Only grant repository access to users who need it

• Use descriptive names to track key usage

• Monitor key usage through audit logs

• Delete unused keys promptly

4. Separation of Environments

Create separate keys for different environments:

// Production
await client.createRepoAiApiKey("repo-123", {
  name: "Production OpenAI Key",
  aiType: "OPENAI"
});

// Development
await client.createRepoAiApiKey("repo-123", {
  name: "Development OpenAI Key",
  aiType: "OPENAI"
});

// Testing
await client.createRepoAiApiKey("repo-123", {
  name: "Testing OpenAI Key",
  aiType: "OPENAI"
});

API Key vs AI LLM Configuration

Understanding the difference between these two concepts:

AI LLM Configuration (Workspace-Level)

• Configured at the workspace level

• Contains AI provider endpoints and credentials

• Used to establish connection to AI services

• Managed through AI LLM Management APIs

AI API Keys (Repository-Level)

• Created at the repository level

• Provides authentication for repository-specific AI operations

• Scoped to individual repositories

• Managed through these AI API Key endpoints

Relationship: AI API Keys enable AI features within a repository, which may utilize AI LLM Configurations for actual AI provider communication.

Response Data

Key Creation Response

When you create an API key, you receive:

{
  success: true,
  id: "apikey-uuid",           // Unique identifier
  key: "FB_AI_abc123...",      // Access key (can be retrieved later)
  secret: "secret_xyz789..."   // Secret key (ONLY shown once!)
}

Key List Response

When listing keys, you receive:

{
  success: true,
  apiKeys: [
    {
      id: "apikey-uuid",
      name: "Production Key",
      repoId: "repo-123",
      key: "FB_AI_abc123...",   // Access key visible
      aiType: "OPENAI",
      createdAt: "2024-01-15T10:30:00.000Z",
      deletedAt: null           // null = active
    }
  ]
}

Note: The secret is never returned in list operations or subsequent requests.

Error Handling

Common error scenarios and how to handle them:

403 Forbidden

Cause: User doesn't have access to the repository

try {
  await client.createRepoAiApiKey("repo-123", data);
} catch (error) {
  if (error.status === 403) {
    console.error("Access denied: Check repository permissions");
  }
}

404 Not Found

Cause: API key or repository doesn't exist

try {
  await client.updateRepoAiApiKey("repo-123", "invalid-key-id", data);
} catch (error) {
  if (error.status === 404) {
    console.error("API key not found or already deleted");
  }
}

500 Internal Server Error

Cause: Server-side error during operation

try {
  await client.createRepoAiApiKey("repo-123", data);
} catch (error) {
  if (error.status === 500) {
    console.error("Server error: Try again or contact support");
  }
}

Audit and Compliance

All API key operations trigger system events for audit purposes:

• Created: When a new API key is generated

• Updated: When key properties are modified

• Deleted: When a key is soft-deleted

These events include:

• Timestamp of the operation

• User who performed the action

• Organization and workspace context

• Key metadata (without exposing secrets)

Permissions

All AI API Key endpoints require authentication via BearerAuth. The following access rules apply:

• Users must have access to the repository to manage its API keys

• Only active (non-deleted) keys can be updated

• Deleted keys are filtered from list operations

• Repository administrators have full access to manage keys

TypeScript Client Library

The Flashback TypeScript client provides convenient methods for all AI API Key operations:

import { FlashbackClient } from '@flashbacktech/flashbackclient';

const client = new FlashbackClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://backend.flashback.tech'
});

// Create AI API key
const created = await client.createRepoAiApiKey("repo-123", {
  name: "My AI Key",
  aiType: "OPENAI"
});

// List AI API keys
const keys = await client.getRepoAiApiKeys("repo-123");

// Update AI API key
await client.updateRepoAiApiKey("repo-123", "key-456", {
  name: "Updated Name"
});

// Delete AI API key
await client.deleteRepoAiApiKey("repo-123", "key-456");

Best Practices Summary

1. Store Secrets Securely: Never log or expose API secrets

2. Rotate Regularly: Implement a key rotation schedule

3. Use Descriptive Names: Make keys easy to identify and manage

4. Monitor Usage: Track key usage through audit logs

5. Separate Environments: Use different keys for prod/dev/test

6. Delete Unused Keys: Remove keys that are no longer needed

7. Verify Before Deleting: Test new keys before removing old ones

8. Document Keys: Maintain internal documentation of key purposes

Related Documentation

• AI LLM Management APIs - Configure AI provider connections at workspace level

• Repository APIs - Manage repositories and their configurations

• Policy APIs - Set up AI usage policies and governance

Next Steps

1. Create your first AI API key for a repository

2. Securely store the secret in your secrets management system

3. Configure your AI services to use the key for authentication

4. Monitor usage through audit logs

5. Set up a key rotation schedule