How OpenSEO Integrates with DataForSEO: Complete Implementation Guide

OpenSEO integrates with DataForSEO by routing all SEO data requests—keyword research, backlink analysis, and rank tracking—through a unified backend that authenticates via a Base64-encoded API key, handles task queuing, and applies a 28% markup to raw DataForSEO costs for hosted deployments.

The every-app/open-seo repository provides a self-hostable SEO platform that leverages DataForSEO as its primary data provider. Understanding how OpenSEO integrates with DataForSEO is essential for both hosted users managing credit pools and self-hosted operators connecting directly to the API.

Architecture Overview

OpenSEO acts as an abstraction layer over the DataForSEO API, managing authentication, request queuing, and cost normalization.

Component	Responsibility	Source Reference
DataForSEO Client	Handles HTTP transport, retry logic, and Base64 authentication headers	[src/lib/dataforseo-client.ts](https://github.com/every-app/open-seo/blob/main/src/lib/dataforseo-client.ts)
Self-Host Validation	Verifies DATAFORSEO_API_KEY presence and format before any paid request	[src/shared/selfhost-checks.ts](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts)
Server Functions	Encapsulate business logic for specific features (backlinks, keyword research)	[src/serverFunctions/backlinks.ts](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts)
Billing Module	Converts raw DataForSEO USD costs to hosted credits using a 28% markup	[src/shared/billing.ts](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)

When a user initiates a backlink check or keyword query, the system constructs a task payload, posts it to DataForSEO's live endpoints, and polls the queue until completion. Errors from DataForSEO propagate as structured responses with task-specific status codes (e.g., 20000 indicating success).

Configuration and Setup

Integrating DataForSEO requires obtaining credentials and configuring the environment before the application can execute paid requests.

1. Obtain API Credentials

   DataForSEO uses a simple authentication scheme where the API key is a Base64-encoded string of your email:password combination. According to the self-hosting documentation, new DataForSEO accounts receive a $1 free credit for testing.

   Create your credentials using standard Base64 encoding:

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

   Store this value for the next step. For detailed visual guidance, refer to [web/content/docs/self-hosting/index.md](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/index.md).

2. Configure Environment Variables

   OpenSEO reads the API key from the DATAFORSEO_API_KEY environment variable. In self-hosted deployments, set this in your .env file.

   # .env
   
   DATAFORSEO_API_KEY=YWJjQGV4YW1wbGUuY29tOnBhc3N3b3JkMTIz

   The repository provides a template in .env.example showing required variables. For Docker-specific injection patterns, see [web/content/docs/self-hosting/docker.md](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/docker.md).

3. Validate the Connection

   Before executing any paid operation, OpenSEO validates the configuration. The [src/shared/selfhost-checks.ts](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) module ensures the API key is present and correctly formatted (Base64 with colon separator), preventing runtime failures during expensive operations.

Implementation Details

The integration implements a task-based asynchronous pattern typical of DataForSEO's architecture.

Authentication Flow

The client constructs HTTP Basic Authentication headers using the decoded credentials. The validation logic in [src/shared/selfhost-checks.ts](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) decodes the Base64 string and verifies the email:password structure exists before initializing the client.

Making Data Requests

Server functions encapsulate specific DataForSEO endpoints. For example, the backlink service posts to the /backlinks/live endpoint:

// src/serverFunctions/backlinks.ts (conceptual implementation)
import { dataForSeoClient } from '../lib/dataforseo-client';

export async function getBacklinks(projectId: string, domain: string) {
  const task = await dataForSeoClient.post('/backlinks/live', {
    target: domain,
    // Additional scope parameters
  });
  
  // Poll queue until task completion
  // Cost deducts based on raw USD rates from DataForSEO
  return task;
}

This pattern repeats across features including rank tracking, site audits, and AI-search visibility queries.

Cost Calculation and Billing

For hosted deployments, OpenSEO applies a markup to raw DataForSEO costs. The billing module converts USD values to platform credits:

// src/shared/billing.ts (excerpt)
export function rawToHostedCost(rawUsd: number): number {
  const MARKUP = 1.28; // 28% OpenSEO markup
  return Math.round(rawUsd * MARKUP * 100) / 100;
}

Self-hosted users bypass this logic and pay DataForSEO directly at published rates.

Monitoring Usage

Track your DataForSEO consumption through built-in tooling. The [src/server/mcp/tools/whoami.ts](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts) command provides a zero-cost method to verify connectivity:

npm run cli whoami

This outputs your authenticated user details and remaining DataForSEO balance without consuming credits.

For detailed usage statistics, run the utility script:

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

This queries your current credit balance and recent consumption patterns, as implemented in [scripts/dataforseo-account-usage.ts](https://github.com/every-app/open-seo/blob/main/scripts/dataforseo-account-usage.ts).

Summary

• Authentication: OpenSEO uses Base64-encoded email:password strings via the DATAFORSEO_API_KEY environment variable.
• Validation: The system checks credential format at runtime through [src/shared/selfhost-checks.ts](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts).
• Architecture: Task-based async requests to DataForSEO endpoints are managed through server functions like [src/serverFunctions/backlinks.ts](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts).
• Pricing: Hosted services add a 28% markup to raw DataForSEO costs via [src/shared/billing.ts](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts), while self-hosted users pay provider-direct rates.
• Testing: Use the whoami CLI command to verify integration without spending credits.

Frequently Asked Questions

What is the format of the DataForSEO API key in OpenSEO?

The API key must be a Base64-encoded string of your DataForSEO email and password separated by a colon (email:password). OpenSEO stores this in the DATAFORSEO_API_KEY environment variable and decodes it for HTTP Basic Authentication headers.

How does OpenSEO handle DataForSEO costs for self-hosted users?

Self-hosted deployments bypass OpenSEO's credit system entirely. Users pay DataForSEO directly at their published API rates. The [src/shared/billing.ts](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) markup logic only applies to the hosted SaaS version where OpenSEO manages the credit pool.

Which OpenSEO features rely on DataForSEO data?

Core features including backlink analysis ([src/serverFunctions/backlinks.ts](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts)), keyword research, rank tracking, site audits, and AI-search visibility all route requests through the DataForSEO integration. Without a valid API key, these features return configuration errors.

How can I test my DataForSEO connection without consuming credits?

Run the whoami CLI command implemented in [src/server/mcp/tools/whoami.ts](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts). This endpoint authenticates against DataForSEO's account API and returns your user profile and balance without deducting credits.

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