# How OpenSEO Integrates with DataForSEO: Complete Implementation Guide

> Learn how OpenSEO integrates with DataForSEO for SEO data. Our guide covers API key authentication, task queuing, and cost markup for seamless implementation. Get started today.

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

---

**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](https://github.com/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)](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)](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)](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)](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:

   ```bash
   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)](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.

   ```text
   # .env

   DATAFORSEO_API_KEY=YWJjQGV4YW1wbGUuY29tOnBhc3N3b3JkMTIz
   ```

   The repository provides a template in [`.env.example`](https://github.com/every-app/open-seo/blob/main/.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)](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)](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)](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:

```typescript
// 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:

```typescript
// 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)](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts) command provides a zero-cost method to verify connectivity:

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

```bash
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)](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)](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)](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)](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)](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)](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)](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.