Authentication

DialogueDB uses bearer token authentication to secure all API requests. This page explains how to authenticate your requests and manage your API tokens.

Bearer Token Authentication

All API requests must include a valid API key in the Authorization header:

Authorization: Bearer DIALOGUE_DB_API_KEY

Making Authenticated Requests

Include your token in every API request:

cURL

curl -X GET https://api.dialoguedb.com/dialogue \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

TypeScript (fetch)

const response = await fetch('https://api.dialoguedb.com/dialogue', {
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
    'Content-Type': 'application/json'
  }
});

SDK

import { DialogueDB } from 'dialogue-db';

const db = new DialogueDB({
  apiKey: 'DIALOGUE_DB_API_KEY'
});

// API key automatically included in all requests
const { items } = await db.listDialogues();

Obtaining API Keys

API keys are managed at the project level through the DialogueDB dashboard. To obtain a key:

1. Log in to app.dialoguedb.com
2. Navigate to your project settings
3. Generate a new API key
4. Copy the key immediately - it will only be displayed once

IMPORTANT

API keys are shown only once and cannot be retrieved again. If you lose your key, you must generate a new one and update your applications. There is no way to view an existing key after creation.

Once you have your key, use it to make requests to api.dialoguedb.com

Security Notice

API keys provide full access to your project's data. Keep them secure and never expose them in client-side code or public repositories.

API Key Scopes

API keys are scoped to specific projects:

• Project Isolation: Each key is tied to a single project
• Full Access: Keys have complete read/write access to all dialogues, messages, memories, and state within their project

Security Best Practices

Store API Keys Securely

• Use environment variables to store API keys
• Never commit keys to version control
• Rotate keys regularly
• Use secret management services in production

Environment Variables

# .env file (never commit this!)
DIALOGUE_DB_API_KEY=your_api_key_here

SDK

import { DialogueDB } from 'dialogue-db';

// Load API key from environment variable
const db = new DialogueDB({
  apiKey: process.env.DIALOGUE_DB_API_KEY
});

TypeScript (fetch)

// For non-SDK usage, load from environment
const apiKey = process.env.DIALOGUE_DB_API_KEY;

const response = await fetch('https://api.dialoguedb.com/dialogue', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

Server-Side Only

API keys should only be used in server-side code:

Good: Backend API, serverless functions, server-rendered apps Bad: Client-side JavaScript, mobile apps, browser extensions

For client-side applications, implement a backend proxy:

// Backend proxy (Express.js example)
app.post('/api/chat', async (req, res) => {
  const db = new DialogueDB({
    apiKey: process.env.DIALOGUE_DB_API_KEY // Server-side only
  });

  const dialogue = await db.getDialogue(req.body.dialogueId);
  const message = await dialogue.saveMessage(req.body.message);

  res.json(message);
});

// Client-side code
const response = await fetch('/api/chat', {
  method: 'POST',
  body: JSON.stringify({ dialogueId, message })
});

Key Rotation

Rotate API keys periodically for enhanced security:

1. Generate a new API key
2. Update your application configuration
3. Deploy the change
4. Revoke the old key

Monitor API Key Usage

Track API key usage to detect unauthorized access:

• Monitor request patterns through your application logs
• Review API usage metrics in your dashboard
• Track rate limit consumption

Error Responses

401 Unauthorized

Missing or invalid authentication:

{
  "message": "Unauthorized"
}

Common causes:

• Missing Authorization header
• Invalid API key format
• Expired or revoked API key

Solution: Verify your API key and header format.

403 Forbidden

Valid API key but insufficient permissions:

{
  "message": "Access denied to resource"
}

Common causes:

• Accessing resources outside your project
• Attempting operations on resources that don't belong to you

Solution: Verify the resource belongs to your project.

HTTPS Only

All API requests must use HTTPS. HTTP requests will be rejected:

# Will fail
curl http://api.dialoguedb.com/dialogue

# Correct
curl https://api.dialoguedb.com/dialogue

Rate Limiting

API keys are subject to rate limits and monthly quotas based on your plan: Rate limit headers are included in responses:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

When rate limited, you'll receive a 429 Too Many Requests response.

Technical Limits

The following technical constraints apply to all API requests regardless of your plan:

Content Size Limits

Resource	Limit	Description
Message Content		Maximum size for message content
Message Metadata		Maximum size for message metadata
Memory Content		Maximum size for memory content
Memory Metadata		Maximum size for memory metadata
Dialogue Metadata		Maximum size for dialogue metadata

These limits are enforced at the API level to ensure system stability and performance. Requests exceeding these limits will return a 400 Bad Request error with details about the constraint violation.

Example: Complete Authentication Flow

Here's a complete example showing proper authentication:

import { DialogueDB } from 'dialogue-db';

// Initialize client with API key from environment
const db = new DialogueDB({
  apiKey: process.env.DIALOGUE_DB_API_KEY
});

// Error handling for authentication issues
try {
  const dialogue = await db.createDialogue({
    messages: [{
      role: 'user',
      content: 'Hello!'
    }]
  });

  console.log('Success:', dialogue.id);
} catch (error) {
  if (error.status === 401) {
    console.error('Authentication failed: Invalid API key');
  } else if (error.status === 403) {
    console.error('Access denied: Insufficient permissions');
  } else {
    console.error('Request failed:', error.message);
  }
}

Next Steps

• Quickstart Guide - Start making authenticated requests
• API Reference - Explore all available endpoints
• Best Practices - Learn about error handling and retry strategies