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

> Learn the DataForSEO API key format for OpenSEO. Understand how to use your Base64 encoded email and password for authentication, not the dashboard token.

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

---

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

```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)

```bash

# 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

```bash
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`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) and [`src/lib/selfhost-preflight.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/lib/selfhost-preflight.ts) | Runtime validation that warns when the key is missing or incorrectly formatted |
| [`src/shared/selfhost-checks.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) | Contains comments clarifying the required Base64 `login:password` encoding |
| [`docs/DATAFORSEO_API_KEY.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts), and [`src/lib/selfhost-preflight.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.