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

> Configure DataForSEO API credentials for your self-hosted OpenSEO deployment by setting the DATAFORSEO_API_KEY environment variable to enable keyword research, backlink analysis, and rank tracking.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-19

---

**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:

```bash
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`:

```dotenv

# .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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```dotenv

# .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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
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`](https://github.com/every-app/open-seo/blob/main/src/web/src/routes/api/backlink-check.ts) abort with error messages defined in [`src/client/lib/error-messages.ts`](https://github.com/every-app/open-seo/blob/main/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:

```bash
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:

```bash
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.