Authentication

DataBlue accepts account JWTs and API keys as Bearer tokens. Use API keys for applications and automation.

JWT Authentication

Obtain a JWT token by authenticating with your email and password:

curl -X POST "https://api.datablue.dev/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

# Response: {"access_token": "eyJ...", "token_type": "bearer"}

API Key Authentication

Create API keys in the Dashboard or with a verified account JWT. The full secret is shown only once.

# Use your API key in every request
curl -X POST "https://api.datablue.dev/v1/scrape" \
  -H "Authorization: Bearer $DATABLUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Create a Programmatic API Key

The API-key creation endpoint requires a verified user. Log in to obtain a JWT, then use that JWT once to create a named application key.

1. Log in and capture the JWT

export DATABLUE_JWT="$(
  curl --fail-with-body --silent --show-error \
    -X POST "https://api.datablue.dev/v1/auth/login" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "you@example.com",
      "password": "YourStrongPassword1"
    }' | jq -r '.access_token'
)"

test -n "$DATABLUE_JWT" && echo "JWT captured"

2. Confirm the authenticated account

curl --fail-with-body --silent --show-error \
  "https://api.datablue.dev/v1/auth/me" \
  -H "Authorization: Bearer $DATABLUE_JWT" | jq '{
    email,
    is_verified,
    plan
  }'

If is_verified is false, complete email verification before creating the key.

3. Create and save the key once

curl --fail-with-body --silent --show-error \
  -X POST "https://api.datablue.dev/v1/auth/api-keys" \
  -H "Authorization: Bearer $DATABLUE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-ingestion"}' | tee datablue-key.json

export DATABLUE_API_KEY="$(jq -r '.full_key' datablue-key.json)"
rm datablue-key.json

The full_key value is shown only in the creation response. Store it in a secrets manager or protected environment variable immediately.

Register Through the API

Registration returns a JWT. Passwords must contain at least eight characters, one uppercase letter, one lowercase letter, and one digit.

curl --fail-with-body --silent --show-error \
  -X POST "https://api.datablue.dev/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "YourStrongPassword1",
    "name": "Your Name"
  }' | jq .

Send Credentials Correctly

JWTs and API keys use the same header syntax:

Authorization: Bearer YOUR_CREDENTIAL

Keep keys in environment variables or secret storage. Never place them in URLs, request bodies, or MCP arguments.

List and Revoke Keys

List active and historical key records

curl --fail-with-body --silent --show-error \
  "https://api.datablue.dev/v1/auth/api-keys" \
  -H "Authorization: Bearer $DATABLUE_JWT" | jq .

List responses contain the key id, prefix, name, active state, creation time, and last-used time. They never return the full secret.

Delete a key

export KEY_ID="00000000-0000-0000-0000-000000000000"

curl --fail-with-body --silent --show-error \
  -X DELETE "https://api.datablue.dev/v1/auth/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $DATABLUE_JWT" | jq .

Use Environment Variables

# Local shell
export DATABLUE_API_KEY="wh_your_api_key"

# .env file used by your application
DATABLUE_API_KEY=wh_your_api_key

# Verify only that a value exists; never print the secret
test -n "$DATABLUE_API_KEY" && echo "DataBlue key configured"

• Add .env files to .gitignore.
• Use separate named keys for local development, CI, staging, and production.
• Inject production keys from your deployment platform or secrets manager.
• Rotate a key by creating its replacement, updating consumers, confirming traffic, and then deleting the old key.

Authentication Troubleshooting

Security Checklist

• Never expose DataBlue credentials in browser-delivered JavaScript.
• Send requests from your backend, trusted worker, CLI, SDK process, or local MCP client.
• Never commit credentials, paste them into public issue reports, or include them in screenshots.
• Redact the Authorization header from logs and tracing systems.
• Use distinct named keys so a single integration can be rotated or revoked independently.
• Delete unused keys and investigate unexpected last_used_at values.