Getting Started

Authentication

Secure your Chatsby AI API requests with API keys — generation, usage, rotation, scoping, and security best practices.

Every request to the Chatsby API must be authenticated with a valid API key. This guide covers everything you need to know about generating keys, using them securely, rotating them without downtime, and handling authentication errors.

API Key Types

Chatsby issues two types of API keys, each operating in an isolated environment:

Key Type	Prefix	Purpose	Data Access
Production	`chtb_live_`	Live applications serving real users	Full access to production data
Test	`chtb_test_`	Development, staging, and CI/CD	Isolated test environment only

Test keys behave identically to production keys — same endpoints, same rate limits, same response shapes — but they operate against a separate dataset. This means you can safely develop and test integrations without affecting your live agents or conversations.

Test keys never touch production data. You can create agents, add sources, and send messages freely during development without any risk to your live environment.

Generating API Keys

Open the API Keys page

Create a new key

Click Create API Key. Enter a descriptive name (e.g., "Production - Backend Server" or "Staging - CI Pipeline") so you can identify the key later.

Select the key type

Choose Production or Test depending on your use case.

Set permissions (optional)

If your plan supports key scoping, select the specific permissions this key should have. See the Key Scoping section below.

Copy and store the key

The full key is displayed only once. Copy it immediately and store it in a secure location such as an environment variable or a secrets manager. You will not be able to view the full key again.

Using API Keys

Pass your API key as a Bearer token in the Authorization header of every request. Do not pass it as a query parameter — query parameters can appear in server logs and browser history.

cURL

curl https://api.chatsby.co/v1/agents \
  -H "Authorization: Bearer chtb_live_abc123def456"

JavaScript (fetch)

const response = await fetch('https://api.chatsby.co/v1/agents', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer chtb_live_abc123def456',
    'Content-Type': 'application/json',
  },
});
 
const data = await response.json();
console.log(data);

Python (requests)

import requests
 
response = requests.get(
    "https://api.chatsby.co/v1/agents",
    headers={
        "Authorization": "Bearer chtb_live_abc123def456",
        "Content-Type": "application/json",
    },
)
 
data = response.json()
print(data)

Node.js SDK

The SDK handles authentication automatically when you initialize the client:

import { Chatsby } from '@chatsby/sdk';
 
const chatsby = new Chatsby({
  apiKey: process.env.CHATSBY_API_KEY,
});
 
// No need to pass headers — the SDK handles it
const agents = await chatsby.agents.list();

Key Rotation

Rotating API keys regularly is a security best practice. Chatsby supports zero-downtime rotation so your application never drops requests during the transition.

Generate a new key

Create a new API key in the dashboard. The old key remains active.

Deploy the new key

Update your application's environment variables or secrets manager with the new key. Deploy the change to all instances.

Verify the new key works

Monitor your application logs to confirm requests are succeeding with the new key. Send a test request manually if needed:

curl https://api.chatsby.co/v1/agents \
  -H "Authorization: Bearer chtb_live_NEW_KEY_HERE"

Revoke the old key

Once you have confirmed the new key is working across all services, return to the dashboard and delete the old key. It will stop working immediately.

Both old and new keys are valid simultaneously until you explicitly revoke the old one. This overlap window is what enables zero-downtime rotation.

Key Scoping

On Pro and Enterprise plans, you can restrict what each API key is allowed to do. This follows the principle of least privilege — keys should only have the permissions they need.

Available permission scopes:

Scope	Description
`agents:read`	List and retrieve agents
`agents:write`	Create, update, and delete agents
`sources:read`	List and retrieve sources
`sources:write`	Create, delete, and refresh sources
`conversations:read`	List and retrieve conversations and messages
`conversations:write`	Create conversations and send messages
`webhooks:read`	List webhook configurations
`webhooks:write`	Create, update, and delete webhook endpoints

When a scoped key attempts an action it does not have permission for, the API returns a 403 Forbidden response:

{
  "error": {
    "type": "forbidden_error",
    "message": "This API key does not have the 'agents:write' permission.",
    "code": "insufficient_permissions",
    "status": 403
  }
}

Security Best Practices

API keys grant direct access to your Chatsby account. Treat them like passwords.

Store keys in environment variables

Never hardcode API keys in your source code. Use environment variables instead:

# .env file (add to .gitignore)
CHATSBY_API_KEY=chtb_live_abc123def456

// Access in your application
const apiKey = process.env.CHATSBY_API_KEY;

Never expose keys client-side

API keys must only be used in server-side code. If you need to call the Chatsby API from a browser or mobile app, proxy the request through your own backend server.

Browser → Your Backend Server → Chatsby API
                (API key lives here)

Add your .env file to .gitignore

Prevent accidental commits of sensitive credentials:

# .gitignore
.env
.env.local
.env.production

Use a secrets manager in production

For production deployments, store API keys in a dedicated secrets manager rather than plain environment variables:

AWS Secrets Manager or AWS SSM Parameter Store
Google Cloud Secret Manager
HashiCorp Vault
Doppler or 1Password Secrets Automation

Rotate keys periodically

Set a schedule to rotate API keys at least every 90 days. Many secrets managers support automatic rotation workflows.

Use scoped keys where possible

If your backend service only needs to read conversations, give it a key with conversations:read scope only. This limits the blast radius if a key is compromised.

Common Authentication Errors

401 Unauthorized

The API could not authenticate your request. Common causes:

Cause	Fix
Missing `Authorization` header	Add the header to your request.
Malformed header (e.g., missing `Bearer` prefix)	Use the format `Authorization: Bearer YOUR_KEY`.
Invalid or expired API key	Check the key in your dashboard. Generate a new one if needed.
Using a test key against production (or vice versa)	Verify you are using the correct key type for your environment.

Example error response:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided.",
    "code": "invalid_api_key",
    "status": 401
  }
}

403 Forbidden

The API key is valid but does not have permission to perform the requested action.

Cause	Fix
Key does not have the required scope	Update the key's permissions in the dashboard or use a different key.
Attempting to access a resource owned by a different account	Verify the resource ID belongs to your account.

{
  "error": {
    "type": "forbidden_error",
    "message": "You do not have permission to access this resource.",
    "code": "insufficient_permissions",
    "status": 403
  }
}

Rate Limiting Per Key

Rate limits are applied per API key, not per account. If you have multiple keys, each key gets its own rate limit window. This means you can distribute load across keys if needed, but you should not use this as a workaround for legitimate rate limiting.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute for this key.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the window resets.

If you consistently hit rate limits, contact support to discuss higher limits for your use case.

Revoking Compromised Keys

If you suspect an API key has been exposed or compromised, act immediately:

Revoke the compromised key

Go to Settings > API Keys in the Chatsby Dashboard. Find the compromised key and click Revoke. The key stops working instantly.

Generate a replacement key

Create a new key with the same scopes and permissions as the revoked one.

Deploy the new key

Update the key in all services, environment variables, and secrets managers that referenced the old key.

Audit recent activity

Review your API usage logs for any suspicious activity that occurred while the key was compromised. Look for unexpected agent modifications, data exports, or conversation deletions.

Rotate other credentials

If the key was stored alongside other secrets (database passwords, third-party API keys), consider rotating those as well. A compromised environment may have exposed more than just the Chatsby key.

If you believe your account has been accessed by an unauthorized party, contact [email protected] immediately. Our security team will assist with a full investigation.

Introduction Core Concepts