Authentication | Developer API | Conversation Engine

Overview

Every API request must include your workspace API key as a Bearer token in the Authorization header. There is one API key per workspace - all requests made with it operate within that workspace's scope.

text

Authorization: Bearer <your-api-key>

Getting Your API Key

Log in to your Conversation Engine workspace
Navigate to Settings → API Keys
Click Generate API Key
Copy the key - it will only be shown once

Keep your key secret

Treat your API key like a password. Never expose it in client-side code, public repositories, or logs. Regenerate it immediately if it is compromised.

Using the Key

Include the key in every request header:

bash

curl -X GET http://localhost:3000/api/dev/v1/me \
  -H "Authorization: Bearer sk-your-api-key-here"curl -X GET http://localhost:3000/api/dev/v1/me \
  -H "Authorization: Bearer sk-your-api-key-here"

python

import requests

headers = {
    "Authorization": "Bearer sk-your-api-key-here",
    "Content-Type": "application/json",
}

response = requests.get(
    "http://localhost:3000/api/dev/v1/me",
    headers=headers
)
print(response.json())import requests

headers = {
    "Authorization": "Bearer sk-your-api-key-here",
    "Content-Type": "application/json",
}

response = requests.get(
    "http://localhost:3000/api/dev/v1/me",
    headers=headers
)
print(response.json())

javascript

const response = await fetch("http://localhost:3000/api/dev/v1/me", {
  headers: {
    "Authorization": "Bearer sk-your-api-key-here",
    "Content-Type": "application/json",
  },
});
const data = await response.json();const response = await fetch("http://localhost:3000/api/dev/v1/me", {
  headers: {
    "Authorization": "Bearer sk-your-api-key-here",
    "Content-Type": "application/json",
  },
});
const data = await response.json();

Verifying Your Key

Use the GET /me endpoint to verify your key is valid and see which workspace it belongs to:

bash

curl -X GET http://localhost:3000/api/dev/v1/me \
  -H "Authorization: Bearer <your-api-key>"curl -X GET http://localhost:3000/api/dev/v1/me \
  -H "Authorization: Bearer <your-api-key>"

python

import requests

response = requests.get(
    "http://localhost:3000/api/dev/v1/me",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())import requests

response = requests.get(
    "http://localhost:3000/api/dev/v1/me",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())

javascript

const response = await fetch("http://localhost:3000/api/dev/v1/me", {
  headers: { "Authorization": "Bearer <your-api-key>" },
});
const data = await response.json();const response = await fetch("http://localhost:3000/api/dev/v1/me", {
  headers: { "Authorization": "Bearer <your-api-key>" },
});
const data = await response.json();

Response

json

{
  "workspace": {
    "id": "01JMXYZ...",
    "name": "Acme Corp Workspace",
    "plan": "pro"
  },
  "api_key": {
    "key": "sk-...",
    "created_at": "2026-01-15T10:00:00Z",
    "last_used_at": "2026-02-20T08:30:00Z"
  }
}{
  "workspace": {
    "id": "01JMXYZ...",
    "name": "Acme Corp Workspace",
    "plan": "pro"
  },
  "api_key": {
    "key": "sk-...",
    "created_at": "2026-01-15T10:00:00Z",
    "last_used_at": "2026-02-20T08:30:00Z"
  }
}

Authentication Errors

If your key is missing, expired, or invalid, you receive a 401 Unauthorized response:

json

{
  "detail": "Invalid or expired API key."
}{
  "detail": "Invalid or expired API key."
}

Ensure:

The Authorization header is present on every request
The value starts with Bearer (note the space)
The key has not been regenerated since you last copied it