# How to Integrate OpenSEO with the DataForSEO API: Complete Configuration Guide

> Learn how to integrate OpenSEO with the DataForSEO API by setting your API key. Unlock powerful keyword research, backlink analysis, and rank tracking features easily.

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

---

**Integrating OpenSEO with the DataForSEO API requires Base64-encoding your DataForSEO credentials and setting them as the `DATAFORSEO_API_KEY` environment variable, which enables the backend to route keyword research, backlink analysis, and rank tracking requests through DataForSEO's pay-as-you-go service.**

The [every-app/open-seo](https://github.com/every-app/open-seo) repository is a full-stack SEO analytics platform that uses DataForSEO as its primary data provider. Configuring this connection allows both cloud-hosted and self-hosted deployments to access real-time SEO intelligence while the application handles task queuing, error management, and cost calculations transparently.

## Architecture Overview

OpenSEO abstracts the DataForSEO API behind a unified server layer. When a user requests backlink data or keyword rankings, the backend constructs a **task envelope**, submits it to DataForSEO's queue, and polls for results.

Key components include:

- **DataForSEO Client** – Handles authentication and HTTP transport to DataForSEO endpoints. Located in [[`src/lib/dataforseo-client.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/dataforseo-client.ts)](https://github.com/every-app/open-seo/blob/main/src/lib/dataforseo-client.ts).
- **Self-Host Validation** – Runtime checks ensure the `DATAFORSEO_API_KEY` is present and correctly formatted before any paid request executes. See [[`src/shared/selfhost-checks.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts).
- **Billing Logic** – Converts raw DataForSEO USD rates to hosted credit costs using a markup factor. Implemented in [[`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts).
- **Task Functions** – Server functions like [[`src/serverFunctions/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts)](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts) orchestrate DataForSEO tasks for specific features.

## Prerequisites

Before configuring the integration, ensure you have:

- A DataForSEO account with API access (new accounts receive complimentary credits).
- Your DataForSEO email address and password ready for Base64 encoding.
- Access to environment configuration files for your deployment method.

## Configuration Steps

### 1. Generate Your API Key

DataForSEO uses **HTTP Basic Authentication** requiring a Base64-encoded string of your credentials. Combine your email and password with a colon separator, then encode:

```bash
echo -n 'your-email@example.com:your-password' | base64

```

The output (e.g., `YWJjQGV4YW1wbGUuY29tOnBhc3N3b3Jk`) is your `DATAFORSEO_API_KEY`.

### 2. Configure Environment Variables

Add the encoded key to your environment. For self-hosted deployments, edit [`.env.example`](https://github.com/every-app/open-seo/blob/main/.env.example) and rename it to `.env`:

```text

# .env

DATAFORSEO_API_KEY=YWJjQGV4YW1wbGUuY29tOnBhc3N3b3JkMTIz

```

For Docker deployments, see [[`web/content/docs/self-hosting/docker.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/docker.md)](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/docker.md) for specific injection instructions.

### 3. Verify the Connection

Test your configuration without consuming credits using the built-in `whoami` command. This validates authentication and displays your remaining DataForSEO balance:

```bash
npm run cli whoami

```

This command executes the logic in [[`src/server/mcp/tools/whoami.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts)](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts), which queries the DataForSEO `/v3/serp/google/locations` endpoint to confirm connectivity.

## Usage Examples

**Environment Configuration**

```text

# .env

DATAFORSEO_API_KEY=base64:encoded_string_here
DATABASE_URL=postgresql://...

```

**Programmatic Backlink Request**

The following excerpt from [[`src/serverFunctions/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts)](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts) demonstrates how OpenSEO submits tasks to DataForSEO:

```typescript
import { dataForSeoClient } from '../lib/dataforseo-client';

export async function getBacklinks(projectId: string, domain: string) {
  const payload = [{
    target: domain,
    mode: 'asap',
    filters: ['do_follow', 'active']
  }];
  
  const response = await dataForSeoClient.post('/backlinks/live', payload);
  
  // Poll for task completion and handle 20000 status codes (success)
  return await pollTaskResults(response.data.task_id);
}

```

**Checking Account Usage**

Self-hosted administrators can monitor DataForSEO consumption using the utility script:

```bash
npx ts-node scripts/dataforseo-account-usage.ts

```

This script is defined in [[`scripts/dataforseo-account-usage.ts`](https://github.com/every-app/open-seo/blob/main/scripts/dataforseo-account-usage.ts)](https://github.com/every-app/open-seo/blob/main/scripts/dataforseo-account-usage.ts) and returns your current credit balance and recent usage statistics.

## Cost Structure and Billing

DataForSEO operates on a pay-as-you-go model where each API task has a specific USD cost. OpenSEO handles billing differently depending on your deployment:

- **Self-Hosted**: You pay DataForSEO directly at raw rates. The application passes through costs without markup.
- **Cloud-Hosted**: OpenSEO applies a **28% markup** (multiplier of 1.28) to raw DataForSEO rates. The conversion occurs in [[`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts):

```typescript
export function rawToHostedCost(rawUsd: number): number {
  const MARKUP = 1.28; // 28% OpenSEO markup
  return Math.round(rawUsd * MARKUP * 100) / 100;
}

```

## Summary

- **DataForSEO** provides the underlying SEO data for keyword research, rank tracking, and backlink analysis in OpenSEO.
- The integration requires setting `DATAFORSEO_API_KEY` as a Base64-encoded `email:password` string in your environment.
- **Self-host checks** in [`src/shared/selfhost-checks.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) validate the key before executing paid requests.
- Use the `whoami` CLI command to verify connectivity without spending credits.
- Self-hosted users pay DataForSEO directly, while cloud users purchase credits through OpenSEO at a marked-up rate.

## Frequently Asked Questions

### Do I need a separate DataForSEO account to self-host OpenSEO?

Yes. Self-hosted deployments require you to create your own DataForSEO account and provide your personal API credentials via the `DATAFORSEO_API_KEY` environment variable. You are billed directly by DataForSEO for all API consumption. The cloud-hosted version manages DataForSEO access internally; you simply purchase OpenSEO credits.

### What format must the DATAFORSEO_API_KEY use?

The key must be a **Base64-encoded** string of your DataForSEO login email and password separated by a colon (`email:password`). For example, `user@example.com:password123` becomes `dXNlckBleGFtcGxlLmNvbTpwYXNzd29yZDEyMw==`. The application decodes this in the DataForSEO client to construct the Basic Auth header.

### How can I check my DataForSEO credit balance without making a paid request?

Run the `whoami` command via the CLI (`npm run cli whoami`). This executes a lightweight API call to DataForSEO's locations endpoint that authenticates your credentials but does not deduct credits from your account. Alternatively, use the [`scripts/dataforseo-account-usage.ts`](https://github.com/every-app/open-seo/blob/main/scripts/dataforseo-account-usage.ts) script to fetch detailed balance and usage history.

### Is there a markup on DataForSEO costs for OpenSEO?

Only for the cloud-hosted version. Self-hosted users pay DataForSEO's raw rates directly. The hosted SaaS applies approximately a **28% markup** on top of DataForSEO's base pricing to cover infrastructure and management costs, as implemented in the billing conversion functions.