How to Configure DataForSEO API Credentials for Self-Hosted OpenSEO Deployments

Set the DATAFORSEO_API_KEY environment variable to the Base64-encoded string of your DataForSEO email:password credentials in your environment file or Cloudflare Worker secrets to enable keyword research, backlink analysis, and rank tracking features.

OpenSEO integrates with the third-party DataForSEO service to power all SEO-related functionality. When self-hosting OpenSEO via Docker, Cloudflare Workers, or local development, you must supply valid API credentials as environment variables. Unlike typical API tokens, DataForSEO requires a specific Base64-encoded format derived from your login credentials rather than the dashboard API token.

Understanding the DataForSEO Key Format

OpenSEO expects a specific credential format that differs from standard API keys.

Obtaining Your Credentials

To generate the required key:

1. Sign in to the DataForSEO portal and navigate to the API Access section.
2. Request new credentials and select "Send by email".
3. Copy the Base64 string provided, which represents the Base64 encoding of your-email@example.com:your-password.

This Base64 string is distinct from the dashboard API token displayed in the web interface. Using the raw dashboard token will cause authentication failures.

Base64 Encoding Requirements

The credential must be the Base64 representation of your login credentials joined by a colon:

echo -n "your-email@example.com:your-password" | base64

The output is a string like dXNlckBleGFtcGxlLmNvbTpwYXNzd29yZDEyMw==. This value is what OpenSEO expects as the DATAFORSEO_API_KEY.

Configuring Environment Variables by Deployment Type

OpenSEO supports three primary deployment methods, each with specific file locations for environment variables.

Docker Self-Hosting

For Docker deployments, create a .env file by copying .env.example:

# .env

PORT=3001
AUTH_MODE=local_noauth
DATAFORSEO_API_KEY=QG5lc3RlYWxAZXhhbXBsZS5jb206c2VjcmV0cGFzc3dvcmQ=

The Docker Compose process loads these variables at runtime, and the server reads them via process.env.DATAFORSEO_API_KEY. See docs/SELF_HOSTING_DOCKER.md for complete setup instructions.

Cloudflare Workers

For Cloudflare Workers deployments, set the secret via the dashboard or use .env.selfhost:

1. Open the Cloudflare dashboard → Workers → Your Worker → Settings → Variables & Secrets.
2. Add a Secret named DATAFORSEO_API_KEY with your Base64-encoded value.

TypeScript definitions in worker-configuration.d.ts declare the variable interface, ensuring compile-time safety with env.DATAFORSEO_API_KEY.

Local Development

For local development with pnpm dev or Vite:

# .env.local

DATAFORSEO_API_KEY=QG5lc3RlYWxAZXhhbXBsZS5jb206c2VjcmV0cGFzc3dvcmQ=

The development server reads this file automatically, using the same variable name as production environments.

How OpenSEO Validates and Uses the Key

The codebase implements multiple validation layers to ensure the credential is present and properly formatted.

Startup Validation

When the server initializes, src/lib/selfhost-preflight.ts performs a pre-flight check on DATAFORSEO_API_KEY. If the value resembles a raw dashboard token rather than a Base64-encoded string, the system emits a warning to the console. This catches common configuration errors before any API requests are attempted.

API Request Injection

All DataForSEO requests route through src/server/lib/dataforseo/core.ts, which retrieves the key using getRequiredEnvValue("DATAFORSEO_API_KEY"). The client injects this value into the HTTP Authorization header:

import { getRequiredEnvValue } from "~/server/lib/env";

async function fetchData(endpoint: string, payload: object) {
  const apiKey = await getRequiredEnvValue("DATAFORSEO_API_KEY");
  
  const response = await fetch(`https://api.dataforseo.com/v3/${endpoint}`, {
    method: "POST",
    headers: {
      "Authorization": `Basic ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });
  
  return response.json();
}

If DATAFORSEO_API_KEY is missing or invalid, endpoints like src/web/src/routes/api/backlink-check.ts abort with error messages defined in src/client/lib/error-messages.ts, gracefully disabling SEO features while alerting the administrator.

Code Examples

Generating the Base64 Credential

Use this Node.js or bash command to generate the correct format:

EMAIL="you@example.com"
PASSWORD="your-secret"
DATAFORSEO_API_KEY=$(echo -n "${EMAIL}:${PASSWORD}" | base64)
echo "DATAFORSEO_API_KEY=$DATAFORSEO_API_KEY"

Testing the Configuration with cURL

Verify your credentials work before adding them to OpenSEO:

curl -X POST "https://api.dataforseo.com/v3/keyword_data" \
  -H "Authorization: Basic $DATAFORSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"open source seo tools"}'

A successful response confirms the Base64 encoding is correct and your DataForSEO account has API access enabled.

Summary

• DataForSEO requires Base64 encoding: The DATAFORSEO_API_KEY must be a Base64 string of email:password, not the dashboard API token.
• Environment location varies by platform: Use .env for Docker, Cloudflare Worker Secrets for edge deployment, and .env.local for development.
• Validation happens at startup: src/lib/selfhost-preflight.ts checks the key format and warns about common misconfigurations.
• Centralized usage: All requests flow through src/server/lib/dataforseo/core.ts, which handles authentication header injection automatically.

Frequently Asked Questions

What happens if I use the DataForSEO dashboard API token instead of the Base64 credentials?

OpenSEO will fail to authenticate with DataForSEO services. The system specifically checks for Base64 formatting in src/lib/selfhost-preflight.ts and will emit a warning if the key looks like a raw token. You must use the Base64-encoded email:password string sent via email when requesting API access.

Can I rotate or update the DataForSEO API key without restarting the container?

No. OpenSEO reads DATAFORSEO_API_KEY at startup via getRequiredEnvValue() and holds the value in memory for subsequent requests. To rotate credentials, update the environment variable and restart the Docker container or redeploy the Cloudflare Worker.

Why does OpenSEO require DataForSEO credentials instead of providing its own API?

OpenSEO is an open-source frontend and orchestration layer that aggregates SEO tools. It does not host its own search index or backlink database. DataForSEO provides the underlying data infrastructure, so self-hosted instances must bring their own DataForSEO account and API credentials to power keyword research, rank tracking, and backlink analysis features.

Is the DataForSEO API key stored securely in the codebase?

Environment variables containing the key are never committed to version control. The repository includes .env.example as a template without real values. For Cloudflare Workers, use the Secrets feature rather than plain text variables to ensure the key remains encrypted and is only accessible to the Worker runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}