DataForSEO API Key Format for OpenSEO: Base64‑Encoded Credentials Explained

The DataForSEO API key in OpenSEO is a Base64‑encoded string of your DataForSEO login email and password in email:password format, not the dashboard‑generated API token.

OpenSEO is an open‑source SEO platform that integrates with DataForSEO for search engine data. Unlike typical API integrations that use dashboard tokens, OpenSEO requires a specifically formatted credential that works with HTTP Basic Authentication.

What the DataForSEO API Key Format Actually Is

According to the OpenSEO source code in every-app/open-seo, the DATAFORSEO_API_KEY environment variable must contain the Base64 encoding of your DataForSEO account credentials. The exact format is:

BASE64("your@email.com:yourPassword")

This means you concatenate your DataForSEO login email, a literal colon (:), and your password, then encode the entire string using Base64.

Source Code Evidence

The repository contains explicit documentation in multiple locations:

• web/.env.example — Contains the comment: # DATAFORSEO_API_KEY base64("login:password") for api.dataforseo.com

• src/shared/selfhost-checks.ts — States: // DATAFORSEO_API_KEY is NOT the key shown in the DataForSEO dashboard — it is the base64 of your DataForSEO login:password

• src/lib/selfhost-preflight.ts — Validates the key with the message: "Not set — all SEO data features will be unavailable until it is. It is the base64 of your DataForSEO login:password (NOT the dashboard API key)."

The reason for this format is that OpenSEO's HTTP client attaches this value directly to requests as Authorization: Basic <DATAFORSEO_API_KEY>. Pre‑encoding the credentials eliminates runtime encoding overhead.

How to Generate the DataForSEO API Key

Method 1: Node.js / JavaScript

// Replace with your actual DataForSEO credentials
const email = "your@email.com";
const password = "yourPassword";

// Combine with colon and Base64‑encode
const raw = `${email}:${password}`;
const dataforseoApiKey = Buffer.from(raw).toString("base64");

console.log(dataforseoApiKey);
// Example output: "eW91ckVtYWlsQGV4YW1wbGUuY29tOnlvdXJQYXNzd29yZA=="

Method 2: Command Line (Unix/Linux/macOS)

# One‑liner using Node.js

export DATAFORSEO_API_KEY=$(node -e 'console.log(Buffer.from("your@email.com:yourPassword").toString("base64"))')

# Or using OpenSSL

export DATAFORSEO_API_KEY=$(echo -n "your@email.com:yourPassword" | base64)

Method 3: Testing with curl

curl -s "https://api.dataforseo.com/v3/serp/google/organic/task_post" \
  -H "Authorization: Basic $DATAFORSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language_code":"en","location_code":2840,"priority":1}'

Common Mistakes with the DataForSEO API Key Format

Using the Dashboard API Key

The DataForSEO dashboard generates a separate API token. Do not use this. As documented in src/shared/selfhost-checks.ts and src/lib/selfhost-preflight.ts, this token will not authenticate correctly with OpenSEO's integration.

Forgetting the Colon Separator

The raw string before encoding must include the colon between email and password: email:password. Encoding just the email or just the password will fail.

Including the "Basic" Prefix

Do not prepend Basic to your environment variable. OpenSEO adds this prefix automatically when constructing the Authorization header.

Where OpenSEO Validates the DataForSEO API Key

The repository enforces this format through several checks:

File	Purpose
src/lib/selfhost-preflight.ts	Runtime validation that warns when the key is missing or incorrectly formatted
src/shared/selfhost-checks.ts	Contains comments clarifying the required Base64 login:password encoding
docs/DATAFORSEO_API_KEY.md	User‑facing documentation with generation instructions
web/.env.example	Template showing the correct environment variable format

Summary

• The DataForSEO API key format in OpenSEO is BASE64("email:password"), not the dashboard token
• Source files web/.env.example, src/shared/selfhost-checks.ts, and src/lib/selfhost-preflight.ts explicitly document this requirement
• Generate the key by concatenating your DataForSEO login email, a colon, and your password, then Base64‑encoding the result
• Set the encoded value as the DATAFORSEO_API_KEY environment variable
• The pre‑encoded format enables direct use in Authorization: Basic headers without runtime processing

Frequently Asked Questions

Why can't I use the DataForSEO dashboard API key?

OpenSEO's HTTP client implements Basic Authentication using pre‑encoded credentials. The dashboard token uses a different authentication scheme. As noted in src/shared/selfhost-checks.ts, the integration specifically expects the Base64‑encoded login/password pair to construct valid Authorization: Basic headers.

How do I verify my DataForSEO API key is correctly formatted?

Decode your environment variable with echo "$DATAFORSEO_API_KEY" | base64 -d (on Unix systems). The output should show your email, a colon, and your password with no additional characters or prefixes.

Is the DataForSEO API key format secure?

The Base64 encoding is not encryption—it is reversible encoding. Store the DATAFORSEO_API_KEY value in secure environment variables or secrets managers. Never commit the encoded value to version control, as anyone with access can decode it to reveal your credentials.

What happens if I use the wrong DataForSEO API key format?

OpenSEO's preflight check in src/lib/selfhost-preflight.ts will display a warning: "Not set — all SEO data features will be unavailable until it is." API requests to DataForSEO will fail with authentication errors, and SERP data features will be disabled in the application.

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