Authentication

The SDK supports three authentication methods: API key (recommended), environment variables, and email/password login.

API Key (Recommended)

Pass your API key directly to the constructor. API keys use the wh_ prefix and never expire.

from datablue import DataBlue

# Sync client
client = DataBlue(api_key="wh_your_api_key")
result = client.scrape("https://example.com")
client.close()

# Or use context manager (recommended)
with DataBlue(api_key="wh_your_api_key") as client:
    result = client.scrape("https://example.com")
    print(result.data.markdown)

from datablue import AsyncDataBlue

# Async client
async with AsyncDataBlue(api_key="wh_your_api_key") as client:
    result = await client.scrape("https://example.com")
    print(result.data.markdown)

Environment Variables

Set DATABLUE_API_KEY and optionally DATABLUE_API_URL in your environment, then use from_env():

# Shell — set environment variables
export DATABLUE_API_KEY=wh_your_api_key
export DATABLUE_API_URL=https://api.datablue.dev    # optional, default: http://localhost:8000
export DATABLUE_TIMEOUT=120                          # optional, seconds (default: 60)
export DATABLUE_MAX_RETRIES=5                        # optional (default: 3)

from datablue import DataBlue

# Reads all DATABLUE_* environment variables automatically
with DataBlue.from_env() as client:
    result = client.scrape("https://example.com")
    print(result.data.markdown)

Variable	Required	Default	Description
DATABLUE_API_KEY	Yes	—	Your API key (wh_... prefix)
DATABLUE_API_URL	No	http://localhost:8000	Base URL of the DataBlue API
DATABLUE_TIMEOUT	No	60	Request timeout in seconds
DATABLUE_MAX_RETRIES	No	3	Max retry attempts on transient errors

Email/Password Login

Use login() to authenticate with email and password. This obtains a JWT token (7-day TTL) and stores it internally on the client instance.

from datablue import DataBlue

with DataBlue(api_url="https://api.datablue.dev") as client:
    # Authenticate — JWT is stored automatically
    auth = client.login("you@example.com", "your_password")
    print(f"Token: {auth['access_token'][:20]}...")

    # All subsequent requests use the JWT
    result = client.scrape("https://example.com")
    print(result.data.markdown)

# Async variant
from datablue import AsyncDataBlue

async with AsyncDataBlue(api_url="https://api.datablue.dev") as client:
    await client.login("you@example.com", "your_password")
    result = await client.scrape("https://example.com")