Connect GSC, Ahrefs, and DataForSEO to one workspace

The three data integrations every workspace should have for full functionality. Walk-through, with the trade-offs of bring-your-own-key vs platform-provided.

Why these three

You can run CitationBench without one or more, but capabilities degrade. GSC missing → no indexing. DataForSEO missing → no SERP, no keyword research. Ahrefs missing → no backlink analysis, weaker DR scoring.

Step 1 — Google Search Console

CitationBench uses Google's BOQ RPC under the hood (the same path the GSC UI uses). You connect via OAuth.

curl -X POST .../v1/indexing/gsc-index/config \
  -H "Authorization: Bearer $CITATIONBENCH_API_KEY" \
  -H "X-Workspace-Id: $WS"

Response includes a redirect URL — open it, grant access to your verified properties, return. You'll see your verifiedDomains listed:

{
  "id": "gscc_***",
  "verifiedDomains": ["acme.com", "blog.acme.com"],
  "autoQueueOnPublish": true,
  "alsoIndexNow": true,
  "connectedAt": "2026-05-24T..."
}

Verify:

curl -G .../v1/indexing/gsc-index --data-urlencode "url=https://acme.com"

If you get a domain_not_verified error, the GSC connection isn't seeing your property. Re-auth or add the property in GSC.

Step 2 — DataForSEO

Two patterns:

Platform-provided (default, easiest)

CitationBench provides DataForSEO out of the box; per-call cost is included in the tool credit price.

Nothing to do — you already have access.

BYOK (bring your own key)

For high-volume workspaces, BYOK can be cheaper.

curl -X POST .../v1/workspaces/$WS/integrations -d '{
  "type":     "dataforseo",
  "mode":     "byok",
  "credentials": {
    "username":     "you@acme.com",
    "password":     "***"
  }
}'

Workspace now uses your DataForSEO account for all research.serp.* and research.keyword.* calls; CitationBench charges a smaller "platform" credit fee (orchestration + parsing) per call.

Step 3 — Ahrefs

Same two patterns:

Platform-provided

Limited to lower-volume agency tiers. Check your plan to confirm.

BYOK (recommended for agency)

curl -X POST .../v1/workspaces/$WS/integrations -d '{
  "type":     "ahrefs",
  "mode":     "byok",
  "credentials": {
    "apiKey":  "***"
  }
}'

CitationBench's research.competitor.backlinks, research.competitor.keywords, and DR lookups now use your Ahrefs subscription.

Step 4 — Verify integration health

curl .../v1/workspaces/$WS/health

{
  "status": "healthy",
  "integrations": [
    {
      "name": "google_search_console",
      "status": "healthy",
      "lastCheckedAt": "..."
    },
    { "name": "dataforseo", "status": "healthy", "lastCheckedAt": "..." },
    { "name": "ahrefs", "status": "healthy", "lastCheckedAt": "..." }
  ]
}

A warning status usually means an expiring credential. A failed status means re-auth.

Step 5 — Optional: agency-shared keys

If you're an agency, you can connect Ahrefs + DataForSEO at the agency level and have workspaces inherit:

curl -X POST .../v1/agency/integrations -d '{
  "type":     "ahrefs",
  "mode":     "byok",
  "credentials": { "apiKey": "***" },
  "sharedWithWorkspaces": "all"
}'

Workspaces that don't have their own key fall back to the agency key.

One-shot interactive setup

#!/usr/bin/env bash
set -euo pipefail
KEY="${CITATIONBENCH_API_KEY:?}"
WS="${WORKSPACE_ID:?}"
BASE="https://api.citationbench.com/v1"

echo "1. Opening GSC OAuth flow..."
GSC_URL=$(curl -sf -X POST $BASE/indexing/gsc-index/config \
  -H "Authorization: Bearer $KEY" -H "X-Workspace-Id: $WS" \
  | jq -r '.oauthRedirectUrl')
open "$GSC_URL"
read -p "Press enter once GSC is authorized..."

read -p "DataForSEO username (or blank to use platform-provided): " DFS_USER
if [[ -n "$DFS_USER" ]]; then
  read -sp "DataForSEO password: " DFS_PASS; echo
  curl -sf -X POST $BASE/workspaces/$WS/integrations \
    -H "Authorization: Bearer $KEY" \
    -d "{\"type\":\"dataforseo\",\"mode\":\"byok\",\"credentials\":{\"username\":\"$DFS_USER\",\"password\":\"$DFS_PASS\"}}"
fi

read -p "Ahrefs API key (or blank to use platform-provided): " AHREFS
if [[ -n "$AHREFS" ]]; then
  curl -sf -X POST $BASE/workspaces/$WS/integrations \
    -H "Authorization: Bearer $KEY" \
    -d "{\"type\":\"ahrefs\",\"mode\":\"byok\",\"credentials\":{\"apiKey\":\"$AHREFS\"}}"
fi

echo "Done. Verify with:"
echo "  curl $BASE/workspaces/$WS/health"

Gotchas

• GSC OAuth scopes include read-only access to your properties + URL inspection. We don't request write scopes outside of indexing submission.
• DataForSEO sandbox is real. sk_test_*** keys use DataForSEO's sandbox endpoints automatically — useful for development.
• Ahrefs rate limits vary by tier. Heavy parallel research.competitor.backlinks can hit limits; pace via concurrency.
• GSC quota is 10 URLs / org / day for indexing submissions (Google's UI limit). The platform queues anything over for the next day automatically.
• Cookies expire. GSC cookie sessions rotate automatically, but occasional reCAPTCHA challenges require manual re-auth. The health endpoint will flag this with a warning.

Related

• API: Indexing · gsc index
• API: Research · keyword
• API: Research · serp
• API: Research · competitor
• API: Workspaces
• Concept: Workspaces