Authentication

Learn how to securely authenticate your API requests to access datablocks services.

Overview

The datablocks API uses API keys to authenticate requests. All API requests must include your API key in the Authorization header using the Bearer authentication scheme.

Authentication failures will return a 401 Unauthorized response. Ensure your API key is kept secure and never committed to version control or exposed in client-side code.

Obtaining API Keys

You can generate and manage API keys from your dashboard:

  1. Navigate to the Dashboard
  2. Click on "Create New Key" in the API Keys section
  3. Give your key a descriptive name (e.g., "Production Server", "Development")
  4. Copy the generated key immediately - it will only be shown once

⚠️ Important: Store your API key securely. If compromised, revoke it immediately and generate a new one.

Authentication Method

Bearer Authentication

Include your API key in the Authorization header with the Bearer prefix:

Authorization: Bearer YOUR_API_KEY

All authenticated endpoints require this header. Requests without valid authentication will be rejected.

Code Examples

Python

import requests

API_KEY = "your_api_key_here"
BASE_URL = "/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Example: Train a datablock
response = requests.post(
    f"{BASE_URL}/datablocks/train",
    headers=headers,
    json={
        "model": "qwen",
        "documents": [{"id": "doc1", "text": "Your document content"}],
        "datablock_name": "my-datablock"
    }
)

print(response.json())

cURL

curl /api/v1/datablocks/train \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen",
    "documents": [{"id": "doc1", "text": "Your document content"}],
    "datablock_name": "my-datablock"
  }'

JavaScript / Node.js

const API_KEY = 'your_api_key_here';
const BASE_URL = '/api/v1';

const response = await fetch(`${BASE_URL}/datablocks/train`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'qwen',
    documents: [{ id: 'doc1', text: 'Your document content' }],
    datablock_name: 'my-datablock'
  })
});

const data = await response.json();
console.log(data);

Security Best Practices

Use Environment Variables

Store API keys in environment variables, not in your code:

# .env file
DATABLOCKS_API_KEY=your_api_key_here

# In your code
import os
api_key = os.getenv("DATABLOCKS_API_KEY")

Rotate Keys Regularly

Periodically rotate your API keys, especially if:

  • A team member with access leaves
  • You suspect the key may have been compromised
  • As part of regular security maintenance (every 90 days recommended)

Use Different Keys per Environment

Create separate API keys for:

  • Production environments
  • Staging/testing environments
  • Development environments
  • Different applications or services

This makes it easier to track usage and revoke access when needed.

Never Expose in Frontend Code

API keys should only be used in backend/server-side code. Never include them in:

  • Client-side JavaScript
  • Mobile app code
  • Version control systems
  • Public repositories

Rate Limiting

API keys are subject to rate limits based on your subscription plan. If you exceed your rate limit, you'll receive a 429 Too Many Requests response.

See the Rate Limits documentation for details on limits for each plan tier.

Troubleshooting

401 Unauthorized

If you receive a 401 error, check that:

  • Your API key is correctly included in the Authorization header
  • You're using the Bearer prefix
  • The API key hasn't been revoked
  • There are no extra spaces or newlines in the key

403 Forbidden

A 403 error indicates your API key is valid but doesn't have permission to access the requested resource. This can happen if:

  • Your subscription doesn't include access to certain features
  • You're trying to access another user's resources
  • Your account has restrictions applied