Authentication

All requests to the ZeebeeAI APIs require authentication. This guide explains how to authenticate your API requests, manage your API keys securely, and understand the different authentication options available.

API Keys

ZeebeeAI uses API keys to authenticate requests. You can view and manage your API keys in the API keys section of your ZeebeeAI dashboard.

Your API keys contain sensitive information:

• They can be used to make API requests that count toward your usage limits
• They grant access to all the models and features available to your account
• They can be used to perform administrative operations like creating API keys and managing user permissions

API Key Structure

ZeebeeAI API keys follow this format:

sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Authentication Methods

Bearer Authentication (Recommended)

The recommended way to authenticate with ZeebeeAI APIs is using the Bearer authentication scheme in the Authorization header.

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example using cURL:

curl https://zeebee.ai/models \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example using JavaScript:

fetch('https://zeebee.ai/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Hello' }],
    model: 'gpt-4-turbo'
  })
});

Query Parameter (WebSocket Only)

For WebSocket connections only, you can pass your API key as a query parameter:

wss://zeebee.ai/ws?api_key=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This method is provided for platforms where setting WebSocket headers is difficult, but should be avoided when possible.

Managing API Keys

Creating API Keys

To create a new API key:

1. Log in to your ZeebeeAI account
2. Go to the API Keys section
3. Click "Create New API Key"
4. Give your key a descriptive name and select appropriate permissions
5. Copy and securely store your new API key - it will only be shown once

API Key Best Practices

Revoking API Keys

If an API key is compromised, you should revoke it immediately. Revoked keys cannot be restored, and any services using that key will need to be updated with a new key.

To revoke an API key:

1. Go to the API Keys section in your dashboard
2. Find the key you want to revoke
3. Click the "Revoke" button and confirm

Authentication for SDKs

If you're using one of our official SDKs, you'll typically initialize the client with your API key, and the SDK will handle authentication for you.

JavaScript SDK

import { ZeebeeClient } from 'zeebee-ai-client';

// Initialize the client with your API key
const zeebee = new ZeebeeClient({
  apiKey: 'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
});

Python SDK

from zeebee_ai_client import ZeebeeClient

# Initialize the client with your API key
zeebee = ZeebeeClient(api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

Flutter SDK

import 'package:zeebee_ai/zeebee_ai.dart';

// Initialize the ZeebeeAI client
final zeebee = ZeebeeAI(
  apiKey: 'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
);

Error Handling

If authentication fails, you'll receive a 401 Unauthorized response with an error object:

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

Common authentication errors:

Security Considerations

Client-Side Applications

Never expose your API key in client-side code (such as JavaScript running in a browser). Instead, create a server-side application that makes API calls to ZeebeeAI and exposes only the necessary functionality to your client-side code.

Environment Variables

Store your API keys in environment variables rather than in your application code. This prevents them from being accidentally committed to version control systems.

# Example: Setting an environment variable
export ZEEBEE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Example: Accessing the environment variable in Node.js
const apiKey = process.env.ZEEBEE_API_KEY;

API Key Permissions

ZeebeeAI supports fine-grained permissions for API keys. When creating a new key, you can specify which operations it can perform. This allows you to follow the principle of least privilege and provide only the permissions needed for each specific application.

Available permission scopes include:

• chat:read - Allow reading chat history
• chat:write - Allow creating new chat messages
• models:read - Allow viewing available models
• conversations:read - Allow reading conversation history
• conversations:write - Allow creating and managing conversations
• voice:read - Allow using speech-to-text features
• voice:write - Allow using text-to-speech features
• admin - Full administrative access (use with caution)

Advanced Authentication Topics

Session Handling

For long-running applications, consider implementing a session management system. This allows you to create temporary sessions for clients while keeping your API key secure on the server.

Rate Limiting

API requests are rate-limited based on your subscription tier. When you exceed your rate limit, you'll receive a 429 Too Many Requests response. Rate limits are applied per API key, so using multiple keys can help distribute load in high-traffic applications.

IP Address Restrictions

Enterprise customers can request IP address restrictions to limit which IP addresses can use a particular API key. This provides an additional layer of security by ensuring that even if a key is exposed, it can only be used from authorized networks.