Authentication

The Doctly API uses API keys for authentication. Every request must include your API key in the Authorization header.

Getting Your API Key

Sign in to your Doctly dashboard
Navigate to Settings then API Keys
Click Create API Key
Copy and securely store your key

API keys grant full access to your account. Never share them publicly or commit them to version control.

Using Your API Key

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Example Requests

curl https://api.doctly.ai/api/v1/documents \
  -H "Authorization: Bearer dk_live_abc123..."

import requests

headers = {
    "Authorization": "Bearer dk_live_abc123..."
}

response = requests.get(
    "https://api.doctly.ai/api/v1/documents",
    headers=headers
)

const response = await fetch('https://api.doctly.ai/api/v1/documents', {
  headers: {
    'Authorization': 'Bearer dk_live_abc123...'
  }
});

req, _ := http.NewRequest("GET", "https://api.doctly.ai/api/v1/documents", nil)
req.Header.Set("Authorization", "Bearer dk_live_abc123...")

client := &http.Client{}
resp, _ := client.Do(req)

Environment Variables

Store your API key in an environment variable:

export DOCTLY_API_KEY="dk_live_abc123..."

import os
import requests

api_key = os.environ.get("DOCTLY_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}

const apiKey = process.env.DOCTLY_API_KEY;
const headers = { Authorization: `Bearer ${apiKey}` };

Authentication Errors

401 Unauthorized

Returned when the API key is missing or invalid:

{
  "detail": "Invalid or missing API key"
}

Common causes:

Missing Authorization header
Missing Bearer prefix
Invalid or revoked API key
Using a test key in production or vice versa

403 Forbidden

Returned when the API key does not have permission for the requested resource:

{
  "detail": "Access denied"
}

Security Best Practices

Keep Keys Secret

Never expose API keys in client-side code, public repositories, or logs.

Use Environment Variables

Store keys in environment variables or a secrets manager, not in code.

Rotate Regularly

Create new keys periodically and revoke old ones.

Limit Scope

Create separate keys for different environments like development, staging, production.

Managing API Keys

Revoke a Key

If a key is compromised, revoke it immediately in your dashboard:

Go to Settings then API Keys
Find the key to revoke
Click Revoke

Revoking a key is immediate and cannot be undone. Any applications using that key will stop working.

Testing Your Key

Verify your API key works by listing your documents:

curl https://api.doctly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.doctly.ai/api/v1/documents",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 200:
    print("API key is valid")
    data = response.json()
    print(f"Documents: {data['count']}")
else:
    print(f"Error: {response.json()}")

A successful response confirms your key is working:

{
  "data": [],
  "count": 0
}

API Overview

Documents

Extractors

Collections

Collection Files

Chat

Authentication

Getting Your API Key

Using Your API Key

Example Requests

Environment Variables

Authentication Errors

401 Unauthorized

403 Forbidden

Security Best Practices

Keep Keys Secret

Use Environment Variables

Rotate Regularly

Limit Scope

Managing API Keys

Revoke a Key

Testing Your Key

​Getting Your API Key

​Using Your API Key

​Example Requests

​Environment Variables

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Security Best Practices

Keep Keys Secret

Use Environment Variables

Rotate Regularly

Limit Scope

​Managing API Keys

​Revoke a Key

​Testing Your Key

Getting Your API Key

Using Your API Key

Example Requests

Environment Variables

Authentication Errors

401 Unauthorized

403 Forbidden

Security Best Practices

Managing API Keys

Revoke a Key

Testing Your Key