Managing API Keys

This guide explains how to manage API keys in the AI Controller administration interface. API keys allow applications to authenticate with AI Controller and access LLM services.

API Keys Overview

The API Keys administration page provides comprehensive key management capabilities. You can view existing keys, create new ones, update properties, delete keys, and monitor usage statistics. The interface is accessible to both administrators and regular users, with appropriate permissions for each role.

Note: AI Controller API keys are different from provider API keys. Provider API keys connect AI Controller to external services like OpenAI or Groq and are configured separately in the Providers settings. This guide focuses on AI Controller API keys that your applications use to authenticate with AI Controller.

Accessing API Keys Management

API Keys can be managed in two ways:

1. For administrators: Navigate to Admin -> API Keys to manage all keys in the system

Screenshot: Shows the administrator view of the API Keys management interface. Regular users will see the same columns, but only for their own keys.

1. For regular users: Access the "My API Keys" in the sidebar to manage your own keys

Screenshot: Shows where regular users can access management for their own keys.

Understanding the API Keys Interface

The API Keys interface provides information about each key, including name, owner, provider, usage statistics, and status. For detailed information about the interface columns and their meanings, see the My API Keys section in the Web UI guide.

Screenshot: The Expiry column shows the manually set expiration date (2025-05-02), while the Deleted column shows "No" indicating the key has not been deleted. The key is set to expire but remains active until that date.

Creating and Managing API Keys

For detailed instructions on creating new API keys and managing existing ones (including editing and deletion), refer to the My API Keys section in the Web UI guide. The process is similar for both administrators and regular users, with the key difference being that administrators can:

• Create keys for any user (via an additional User field in the creation dialog)
• View and manage all keys in the system
• See which keys exist (not the actual key value) for all users in the interface

Screenshot: Shows the administrator view of the dialog for creating a new API key with fields for name, user, provider, and expiry

Key Expiration Management

To immediately expire an API key as an administrator:

1. Navigate to Admin -> API Keys
2. Find the target key
3. Click "Expire"
4. Confirm the action

Users can expire their own keys through a similar process in the My API Keys section.

Screenshot: Expire option in the API key action menu

Expiration takes effect immediately, preventing further use of the key while maintaining its record for audit purposes.

API Key Best Practices

Naming Conventions

Create descriptive key names that clearly identify: - The application using the key - The key's intended purpose - Any relevant environment information

Examples of good key names include "Continue.dev Integration", "ML Pipeline API", or "Marketing Team OpenAI Access".

Expiration Guidelines

All keys should have an appropriate expiry date based on their purpose: - Development keys: 30 days - Production keys: 90-180 days - Emergency keys: 1-7 days

Regular key rotation improves security by limiting the impact of potential key compromises.

API Key Management Workflows

Creation and Distribution

Follow these steps for secure key management:

1. Create the key with appropriate settings
2. Share the key immediately with the intended user
3. Implement the key in the target application
4. Confirm successful implementation
5. Document key details (excluding the key itself) for reference

Key Rotation

When rotating API keys:

1. Create a new key with the same settings as the old one
2. Distribute the new key to application owners
3. Allow sufficient time for implementation in all dependent applications
4. Verify the new key works correctly in all systems
5. Delete the old key after confirming it's no longer in use

Monitoring API Key Usage

AI Controller provides tools to monitor user activity related to the keys:

1. Navigate to Logs in the sidebar
2. Filter logs by user
3. Review usage patterns, including request volume, accessed models, and error rates

Using API Keys in Applications

Before implementing API keys in your applications, you need to configure the appropriate provider settings in AI Controller. After configuring your provider, create an AI Controller API key linked to this provider for use in your applications.

Implementation Examples

REST APIPythonJavaScript

POST /work
Host: your-aic-server:9090
Authorization: Bearer YOUR_AIC_API_KEY
Content-Type: application/json

{
  "model": "gpt-4",
  "messages": [
    {"role": "user", "content": "Hello, world!"}
  ]
}

import requests

AIC_API_KEY = "YOUR_AIC_API_KEY"
AIC_URL = "https://your-aic-server:9090/work"

headers = {
    "Authorization": f"Bearer {AIC_API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-4",
    "messages": [
        {"role": "user", "content": "Hello, world!"}
    ]
}

response = requests.post(AIC_URL, json=payload, headers=headers)
print(response.json())

const AIC_API_KEY = 'YOUR_AIC_API_KEY';
const AIC_URL = 'https://your-aic-server:9090/work';

async function queryAIC(prompt) {
  const response = await fetch(AIC_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${AIC_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4',
      messages: [
        {role: 'user', content: prompt}
      ]
    })
  });

  return await response.json();
}

Troubleshooting API Key Issues

Issue	Possible Causes	Solutions
Authentication failed	- Incorrect key - Expired key	- Verify key is correct - Check expiration date - Create a new key if needed
Permission denied	- User lacks required permissions - Rule blocks the request	- Check user permissions - Review applicable rules
Too many requests	- Rate limit exceeded - Usage quota reached	- Implement request batching - Distribute load across multiple keys
Specific model unavailable	- Provider restriction on key - Rule blocks request - Model not enabled in provider configuration	- Check key provider setting - Verify rule configuration - Verify model is enabled in provider configuration

For more detailed troubleshooting assistance, see the Authentication Issues Guide.

Security Best Practices

To maintain strong API key security:

1. Rotate keys regularly
2. Use short expiration periods
3. Assign minimal permissions to each key
4. Monitor usage patterns for anomalies
5. Delete unused keys promptly
6. Store keys securely, never in source control
7. Use different keys for different applications or environments
8. Leverage the built-in ownership tracking (creator and owner) in AIC

API Key Governance for Organizations

For organizations managing numerous API keys:

1. Establish consistent naming conventions
2. Implement approval workflows for key creation
3. Schedule regular key audits
4. Define maximum lifetimes for different key types
5. Create procedures for emergency key expiration
6. Maintain documentation of all keys and their purposes

Related Documentation

• API Key Management

---

Updated: 2025-05-27