API Keys

API keys are the primary authentication method for dialektai's API. They provide secure, token-based access to your databases and organization resources.

Creating API Keys

All API keys are created through the dialektai portal. Navigate to your organization settings or database settings to create new API keys.

ℹ️ API keys are generated and managed exclusively through the web portal for security reasons. They cannot be created programmatically.

Types of API Keys

Organization-Level Keys

Organization-level API keys grant access to all databases within your organization. These are secret keys (prefixed with sk_) intended for server-side use only.

Use Cases:

To create an organization-level key:

  1. Log in to the dialektai portal
  2. Click API Keys in the sidebar
  3. Click Create API Key
  4. Provide a name
  5. Copy the generated key immediately (secret keys are only shown once)
⚠️ Secret keys (sk_*) are shown **only once** when created. Store them securely - they cannot be retrieved later.

Database-Level Keys

Database-level API keys are scoped to a single database connection. These are public keys (prefixed with pk_) designed for client-side embedding. Security is enforced through CORS allowed origins, not by keeping the key secret.

Use Cases:

To create a database-level key:

  1. Log in to the dialektai portal
  2. Navigate to Databases → Select your database
  3. Scroll to the Widget Integration section
  4. In the API Keys panel, click Create New API Key
  5. Provide a name
  6. The key will be displayed and can be copied anytime (public keys remain visible)
ℹ️ Public keys (pk_*) are safe for client-side code and can be viewed anytime. They're protected by CORS allowed origins, not by keeping them secret.

Using API Keys

Authentication Methods

dialektai supports two distinct authentication methods:

  1. JWT Tokens (Web Portal):

    • Format: Authorization: Bearer <JWT_TOKEN>
    • Use case: Authenticated user sessions from the web portal
    • Used for: Creating API keys, managing organization settings

  2. API Keys (Programmatic Access):

    • Format: X-API-Key: <API_KEY>
    • Use case: Widget integrations, backend services, automated scripts
    • Used for: Querying databases, sending chat messages

HTTP Header Format

Include your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Example Requests

cURL:

curl -X POST https://api.dialektai.com/api/v1/chat/message \
  -H "X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Show me sales data",
    "conversation_id": "conv-abc"
  }'

Python:

import requests

headers = {
    'X-API-Key': api_key,
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.dialektai.com/api/v1/chat/message',
    headers=headers,
    json={
        'message': 'Show me sales data',
        'conversation_id': 'conv-abc'
    }
)

JavaScript/TypeScript:

const apiKey = process.env.DIALEKTAI_API_KEY;

const response = await fetch('https://api.dialektai.com/api/v1/chat/message', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Show me sales data',
    conversation_id: 'conv-abc'
  })
});

Key Management

ℹ️ All API key management (viewing, revoking) can only be done through the **dialektai portal**. There is no programmatic API for managing API keys.

Viewing Your Keys

  1. Log in to the dialektai portal
  2. Navigate to:
    • API Keys in the sidebar (for organization-level secret keys)
    • Databases → Select database → Widget Integration section (for database-level public keys)
  3. View key metadata: name, scope, creation date, last used, usage count

Key Visibility:

Revoking Keys

  1. Navigate to the API Keys section in the portal (as above)
  2. Click the delete/revoke button next to the key you want to revoke
  3. Confirm the revocation
🚨 Danger
Revoked keys cannot be recovered. Any applications using a revoked key will immediately lose access. Update your applications with a new key before revoking old ones.

Best Practices

1. Use Environment Variables

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

# .env file
DIALEKTAI_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

import os
api_key = os.getenv('DIALEKTAI_API_KEY')

2. Rotate Keys Regularly

Rotate your API keys every 90 days to minimize security risks:

  1. Create a new API key
  2. Update your applications with the new key
  3. Verify the new key works
  4. Revoke the old key

3. Use Least Privilege

4. Monitor Usage

Track API key usage in the dialektai dashboard:

5. Secure Storage

Key Prefixes

dialektai uses prefixes to identify key types and their intended use:

Prefix Type Scope Intended Use Security Model
sk_ Secret Key Organization Server-side only Keep secret, never expose client-side
pk_ Public Key Database Client-side safe Public, protected by CORS

Key Format:

Security Guidelines:

Rate Limiting

API keys are subject to rate limits based on your plan:

Plan Requests/Minute Requests/Day
Free 10 1,000
Starter 60 10,000
Pro 600 100,000
Enterprise Custom Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1697654400

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY"
}

Causes:

403 Forbidden

{
  "error": "forbidden",
  "message": "API key does not have access to this resource",
  "code": "INSUFFICIENT_PERMISSIONS"
}

Causes:

429 Too Many Requests

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

Solution: Implement exponential backoff and respect the Retry-After header.

Next Steps