API Key Management

​

Overview

• Public Chat API (https://api.talkifai.dev/v1/chat)
• Data Export API (https://api.talkifai.dev/api/export)
• Other public endpoints

​

Key Types

​

1. Secret Key (Server-Side Only)

• ❌ Never expose to browser/client-side code
• ✅ Full access to all APIs
• ✅ No domain restrictions
• ✅ 1-year expiry

# Server-side environment variable
TALKIFAI_API_KEY=your_secret_key_here

# API request
curl -X POST "https://api.talkifai.dev/v1/chat/sessions" \
  -H "X-API-Key: $TALKIFAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id"}'

​

2. Widget Key (Browser-Safe)

• ✅ Safe to include in client-side code
• ✅ Domain-locked (CORS restricted)
• ✅ localhost always allowed for development
• ✅ 1-year expiry

• Requests from unlisted domains are automatically rejected
• Subdomains are automatically covered (e.g., mysite.com also allows staging.mysite.com)
• Can be revoked without affecting other keys

// Frontend JavaScript (safe!)
window.__TALKIFAI__ = {
  apiUrl: "https://api.talkifai.dev/v1/chat",
  widgetKey: "tk_widget_your_key_here", // Safe for browser
  agentId: "your-agent-id",
};

​

Creating an API Key

​

Step 1: Navigate to API Keys

• Owners: Can create and manage keys
• Admins: Can view keys
• Members: Can view keys

​

Step 2: Configure Key Details

​

1. Enter Key Name (Required)

• Max 50 characters
• Examples: “Production Server”, “Website Widget”, “Dev Testing”

​

2. Select Key Type

• For server-side use only
• No domain restrictions
• Full API access

• For browser/frontend use
• Domain-locked (CORS restricted)
• Safe for public embeds

​

3. Add Allowed Domains (Widget Keys Only)

mysite.com, staging.mysite.com, app.mysite.com

• Subdomains are automatically covered (mysite.com includes *.mysite.com)
• localhost is always allowed for development
• Multiple domains: separate with commas
• Protocol (https://) is optional

​

Step 3: Generate Key

• Copy immediately to clipboard
• Store in password manager or environment variables
• Cannot be retrieved later (only the prefix is stored)

​

Key Format

​

Secret Key Format

64-character random string (no prefix)
Example: a8f3k2j9d1m4n7p0q5r8t2u6v3w9x1y...

• No special prefix
• URL-safe characters only
• Unique per key

​

Widget Key Format

tk_widget_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
(32-character random string after prefix)

• tk_widget_ prefix identifies it as browser-safe
• Domain-locked via CORS
• Can be safely exposed in client-side code

​

Key Details

​

Managing Existing Keys

​

View Keys

• Key name
• Key type badge (Secret/Widget)
• Key prefix (first 8 characters + ••••••••)
• Created date
• Expiration date
• Status (Active/Disabled)
• Allowed domains (Widget keys)

​

Revoke a Key

1. Find the key in “Your API Keys” section
2. Click Revoke API Key button
3. Confirm deletion

• Key is immediately invalidated
• All active sessions using the key are terminated
• Cannot be undone

​

API Key Usage

​

Chat API Endpoints

​

Authentication Methods

POST /v1/chat/sessions
X-API-Key: tk_widget_your_key  # or secret key
Content-Type: application/json

{
  "agent_id": "your-agent-id"
}

POST /v1/chat/sessions/{id}/messages
Authorization: Bearer {session_token}
Content-Type: application/json

{
  "message": "Hello"
}

​

Security Best Practices

​

1. Use Widget Keys for Frontend

// Frontend widget config
window.__TALKIFAI__ = {
  widgetKey: "tk_widget_..." // ✅ Safe for browser
};

// Frontend widget config
window.__TALKIFAI__ = {
  apiKey: "a8f3k2j9..." // ❌ Secret key exposed!
};

​

2. Store Secret Keys Securely

# .env.local (never commit to git)
TALKIFAI_API_KEY=your_secret_key_here

// Node.js/Express
app.post('/api/chat/start', async (req, res) => {
  const response = await fetch('https://api.talkifai.dev/v1/chat/sessions', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.TALKIFAI_API_KEY, // ✅ Server-side only
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ agent_id: process.env.AGENT_ID })
  });
  const data = await response.json();
  res.json(data); // Return session_token to frontend
});

​

3. Rotate Keys Periodically

1. Generate new key
2. Update applications with new key
3. Test thoroughly
4. Revoke old key

​

4. Use Separate Keys per Environment

• Production: Production Widget
• Staging: Staging Widget
• Development: Dev Testing

• Isolate issues to specific environment
• Revoke one environment without affecting others
• Track usage per environment

​

Troubleshooting

​

”Invalid API Key” Error

• Key is incorrect or truncated
• Key was revoked
• Wrong key type (Secret vs Widget)

1. Verify key is copied correctly (no extra spaces)
2. Check key status in Organization → API Keys
3. Generate new key if needed

​

”CORS Origin Not Allowed” Error (Widget Keys)

• Request from unlisted domain
• Domain format incorrect

1. Add domain to allowed domains list
2. Include both root and www variants if needed:
   • mysite.com
   • www.mysite.com
3. Save and wait ~1 minute for propagation

​

”Insufficient Credits” Error

• Organization has no credits remaining

1. Go to Organization → Billing
2. Add credits to your organization
3. Retry request

​

Related Documentation

• Chat API Reference — REST API for chat integration
• Widget Integration Guide — Embed widget on your website
• Billing & Credits — Manage organization credits

​

Next Steps