API Key Management

Overview

API keys are the primary authentication mechanism for the ChatSDK, connecting your React SDK to backend services. They provide:

• Authentication: Verify the identity of your client application
• Authorization: Control access to resources and features
• Rate Limiting: Enforce usage quotas per project
• Usage Tracking: Monitor and attribute API usage and costs
• Environment Separation: Distinguish between test and production environments

API Key Format

API keys follow a standard format for security and clarity:

chatsdk_{environment}_{secret}

Examples:
  - chatsdk_live_ak1nDk3jF9sL2mP0qR8tU7vW5xY6zB4cE3fG2hI1jK0
  - chatsdk_test_pQ9rS8tU7vW6xY5zB4cE3fG2hI1jK0mN1oP2qR3sT4u

Format Components

Component	Description	Example
Prefix	Service identifier	chatsdk_
Environment	live or test	live_
Secret	32 random bytes (base64url)	ak1nDk3jF9sL2mP0qR8tU7vW5xY6zB4cE3fG2hI1jK0

Creating API Keys

Step 1: Navigate to API Keys

1. Go to the Admin UI dashboard
2. Click API Keys in the sidebar
3. Click Create New Key

Step 2: Configure the Key

Fill in the following options:

• Name (optional): Human-readable name for the key

  • Examples: "Production Key", "Staging Key", "Development Key"
  • Helps identify the key's purpose in your dashboard

• Environment: Select the environment

  • Live: For production applications
  • Test: For development and testing

• Expires In (optional): Set an expiration date

  • Options: 30, 60, 90 days, or never
  • Recommended: Set expiration for enhanced security
  • You can create a new key before expiration

Step 3: Save Your Key

IMPORTANT: The full API key is displayed only once after creation.

1. Copy the entire key to a secure location
2. Save it in your environment variables (.env file)
3. Click "Done" - you cannot retrieve the full key later

Viewing API Keys

List of Keys

The API Keys dashboard shows:

• Key Prefix: First 20 characters (e.g., chatsdk_live_ak1nDk3j...)
• Name: Your label for the key
• Environment: Live or Test
• Created: When the key was created
• Last Used: When the key was last used
• Status: Active, Revoked, or Expired
• Actions: Revoke or Delete

Key Details

Click on any key to see:

• Full prefix (cannot see full key again)
• Permissions granted
• Rate limit status
• Usage statistics
• Revocation history

Using API Keys in Your Application

React SDK

import { ChatProvider } from '@cyborg-sdk/react';

function App() {
  return (
    <ChatProvider
      apiKey={process.env.REACT_APP_CHATSDK_API_KEY}
      apiUrl="https://api.chatsdk.com"
    >
      <YourApp />
    </ChatProvider>
  );
}

Environment Variables

.env.local (development):

REACT_APP_CHATSDK_API_KEY=chatsdk_test_pQ9rS8tU7vW6xY5zB4cE3fG2hI1jK0mN1oP2qR3sT4u

.env.production (production):

REACT_APP_CHATSDK_API_KEY=chatsdk_live_ak1nDk3jF9sL2mP0qR8tU7vW5xY6zB4cE3fG2hI1jK0

Important: Add .env.* to your .gitignore to prevent accidentally committing API keys.

Managing API Keys

Rotate a Key

To safely rotate an API key without downtime:

1. Create new key with same environment
2. Update application to use new key (via environment variable update)
3. Verify new key is working in production
4. Revoke old key after confirming no issues

Revoke a Key

Revoke a key immediately to prevent further use:

1. Click Revoke on the key
2. Confirm the action
3. The key cannot be used for new requests
4. Active connections may continue briefly

When to revoke:

• Security compromise (key leaked)
• Team member departure
• End of environment (e.g., staging shutdown)
• Key rotation

Delete a Key

Permanently delete a key from your account:

1. Click Delete on the key
2. Confirm the action
3. The key cannot be recovered
4. All history for this key is removed

Note: Deleted keys cannot be recovered. Revoke instead if you might need it later.

Test vs Live Keys

Test Keys (chatsdk_test_)

Use for development and testing:

Feature	Details
Rate Limits	Lower (50 req/min)
LLM Backend	Sandbox/cheaper models
Data Isolation	Separate vector collections
Cost Attribution	Not billed or minimal
Dashboard UI	Clearly marked "TEST"
Usage Tracking	Tracked separately

Live Keys (chatsdk_live_)

Use for production:

Feature	Details
Rate Limits	Production limits (per plan)
LLM Backend	Production Claude API
Data Isolation	Production data
Cost Attribution	Full billing
Dashboard UI	Clearly marked "LIVE"
Usage Tracking	Full analytics

Rate Limiting

Each API key has a rate limit that varies by plan:

Plan	Rate Limit	Cost
Free	50 req/min	$0
Starter	100 req/min	$25/mo
Growth	500 req/min	$99/mo
Pro	2000 req/min	$299/mo
Enterprise	Custom	Custom

When you exceed your rate limit:

• Status: 429 Too Many Requests
• Response includes: Time when limit resets
• Headers include: X-RateLimit-Reset timestamp

Handling rate limits in your SDK:

try {
  await sendMessage("Hello");
} catch (error) {
  if (error.status === 429) {
    const resetTime = error.headers['X-RateLimit-Reset'];
    console.log(`Rate limit exceeded. Resets at ${resetTime}`);
    // Implement retry logic with exponential backoff
  }
}

Permissions

API keys can be scoped to specific permissions:

Available Permissions

• chat - Send messages and receive responses
• upload - Upload documentation
• analytics - Access usage analytics
• admin - Full administrative access

Setting Permissions

When creating a key, you can limit its permissions:

1. During key creation, check the permissions
2. Uncheck any permissions the key doesn't need
3. Save the key with limited scope

Best Practice: Grant only the minimum permissions needed for each integration.

Security Best Practices

1. Never Hardcode Keys

Bad:

// ❌ Don't hardcode keys
<ChatProvider apiKey="chatsdk_live_ak1nDk3jF9sL..." />

Good:

// ✅ Use environment variables
<ChatProvider apiKey={process.env.REACT_APP_CHATSDK_API_KEY} />

2. Keep Keys Out of Git

Add to .gitignore:

echo ".env" >> .gitignore
echo ".env.local" >> .gitignore
echo ".env.*.local" >> .gitignore

3. Rotate Regularly

• Set expiration dates (30-90 days)
• Rotate before expiration
• Rotate after team member departure

4. Monitor Usage

• Check "Last Used" dates regularly
• Revoke unused keys
• Monitor usage in Analytics dashboard

5. Limit Scope

• Create separate keys for each environment
• Use test keys in development
• Create keys with only needed permissions

6. Secure Storage

Development:

# .env.local (never commit)
REACT_APP_CHATSDK_API_KEY=chatsdk_test_...

Production:

• Use your hosting platform's secrets manager
  • Vercel: Environment Variables
  • Netlify: Build & Deploy → Environment
  • Heroku: Config Vars
  • AWS: Secrets Manager
  • Azure: Key Vault

Server-side:

const apiKey = process.env.CHATSDK_API_KEY;
if (!apiKey) {
  throw new Error('CHATSDK_API_KEY not set');
}

Troubleshooting

"Invalid API Key" Error

Causes:

• Key is revoked (check dashboard)
• Key is expired (check expiration date)
• Key format is incorrect (should start with chatsdk_)
• Key has typos

Solution: Create a new key and update your environment variable.

"Permission Denied" Error

Causes:

• Key doesn't have required permission
• Key environment doesn't match use case
• Key's project doesn't match request

Solution: Check key permissions or create a new key with needed permissions.

"Rate Limit Exceeded" Error

Causes:

• Your application is sending too many requests
• Too many concurrent users
• Inefficient implementation

Solutions:

1. Implement caching to reduce requests
2. Batch requests where possible
3. Upgrade to a higher plan
4. Optimize your chat implementation

Key Not Working in Production

Causes:

• Environment variable not set correctly
• Using test key in production
• Key expired
• Key revoked

Solution: Verify environment variable is set, use live key, check expiration date.

Next Steps

1. Create your project
2. Upload documentation
3. Install the SDK
4. Review security best practices

Related Documentation

• Security Best Practices - Comprehensive security guide
• SDK Configuration - How to pass API key to SDK
• Troubleshooting Guide - Common setup issues