Skip to main content
All Chatbot Platform API requests require authentication using API keys. This guide covers how to create, manage, and use API keys securely.

​
API Keys

API keys are bearer tokens that authenticate requests to the Chatbot Platform API.

​
Creating an API Key

1

Go to Settings

Navigate to your team settings in the dashboard.
2

Open API Keys

Click API Keys in the sidebar.
3

Create New Key

Click Create API Key.Provide:
  • Name: Descriptive name (e.g., “Production Server”)
  • Permissions: Select scopes (all by default)
4

Copy Key

Copy the generated key immediately - it won’t be shown again.Format: sk_live_abc123xyz...
5

Store Securely

Save the key in your environment variables or secrets manager.
API keys provide full access to your team’s resources. Never share them or commit them to version control.

​
Using API Keys

Include your API key in the Authorization header: 
curl https://api.chatbotplatform.io/v1/bots \
  -H "Authorization: Bearer sk_live_abc123xyz..."

​
Environment Variables

Store keys as environment variables: Bash: 
export CHATBOT_API_KEY="sk_live_abc123xyz..."
Node.js: 
const apiKey = process.env.CHATBOT_API_KEY;

fetch('https://api.chatbotplatform.io/v1/bots', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});
Python: 
import os
import requests

api_key = os.environ['CHATBOT_API_KEY']

response = requests.get(
    'https://api.chatbotplatform.io/v1/bots',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
)

​
Key Types

​
Live Keys

Production keys with full access: 
sk_live_abc123xyz...
Use for production environments only.

​
Test Keys (Coming Soon)

Sandbox keys for development: 
sk_test_abc123xyz...
Use for development and testing without affecting production data.

​
Permissions and Scopes

API keys can have restricted permissions:
ScopeAccess
bots:readView bots
bots:writeCreate/update bots
integrations:readView integrations
integrations:writeCreate/update integrations
channels:readView channels
channels:writeCreate/update channels
conversations:readView conversations
conversations:writeDelete conversations
agent-loops:readView agent loops
agent-loops:writeCreate/run agent loops
adminFull access to everything

​
Creating Restricted Keys

For security, create keys with minimal required permissions: 
Production API Key:
Permissions:
  ✓ bots:read
  ✓ conversations:read
  ✗ bots:write
  ✗ admin
This key can view but not modify resources.

​
Authentication Errors

​
Invalid Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}
Status: 401 Unauthorized Causes:
  • Key is incorrect
  • Key was deleted
  • Wrong key format

​
Expired Key (Coming Soon)

{
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "This API key has expired"
  }
}
Status: 401 Unauthorized

​
Insufficient Permissions

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API key does not have permission to perform this action",
    "required_scope": "bots:write"
  }
}
Status: 403 Forbidden

​
Key Management

​
Rotating Keys

Periodically rotate API keys for security:
1

Create New Key

Generate a new API key with the same permissions.
2

Update Applications

Deploy the new key to all services using it.
3

Verify

Confirm all services are using the new key successfully.
4

Delete Old Key

Remove the old key to prevent unauthorized access.

​
Revoking Keys

Immediately revoke a key if compromised:
1

Go to API Keys

Navigate to API Keys settings.
2

Find Key

Locate the compromised key.
3

Delete

Click Delete to revoke immediately.
4

Create New

Generate a replacement key.
Deleted keys stop working immediately.

​
Webhook Authentication

For incoming webhooks (callbacks, bot messages), verify requests using signatures:

​
Webhook Signature

Incoming webhooks include a signature header: 
X-Chatbot-Signature: sha256=abc123...

​
Verifying Signatures (Coming Soon)

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const computed = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-chatbot-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook...
});

​
Security Best Practices

Use Environment Variables

Never hardcode API keys in source code

Rotate Regularly

Change keys every 90 days or when employees leave

Minimal Permissions

Grant only necessary scopes per key

Secure Storage

Store keys in environment variables or secrets managers

​
Secure Storage

Do:
  • Use environment variables
  • Store in secrets managers (AWS Secrets Manager, HashiCorp Vault)
  • Encrypt at rest
  • Restrict access to keys
Don’t:
  • Commit to Git
  • Store in plaintext files
  • Share via email or chat
  • Use same key across all environments

​
Production vs Development

Use separate keys for each environment: 
Development: sk_live_dev_...
Staging: sk_live_staging_...
Production: sk_live_prod_...
This isolates environments and limits blast radius if compromised.

​
Rate Limiting

API keys are subject to rate limits. See API Introduction for details.

​
Troubleshooting

​
Authentication Fails

Check:
  • Key is correct and complete
  • Authorization header format: Bearer YOUR_KEY
  • No extra spaces or characters
  • Key hasn’t been deleted

​
Intermittent Failures

Possible Causes:
  • Rate limiting
  • Clock skew (for signatures)
  • Network issues
Solutions:
  • Implement exponential backoff
  • Sync system clock
  • Add retry logic

​
Key Not Working After Creation

Wait a few seconds: Keys may take 5-10 seconds to propagate.

​
Next Steps

API Introduction

Learn about API basics

Bot Management

API endpoints for bots (coming soon)