🔐 Semrush - Authentication & Projects

Overview

Semrush uses API key authentication with project-based configuration. Each account can save project settings that associate a domain with Semrush project and campaign IDs for position tracking.

API Key Configuration

Environment Variables

SEMRUSH_API_KEY=your_api_key_here
SEMRUSH_API_URL=https://api.semrush.com/
SEMRUSH_DATABASE=us

How to Get API Key

1. Log in to Semrush
2. Navigate to Settings → API & Integrations
3. Copy your API key
4. Add to DashClicks environment variables

Project Management

Save Project Configuration

POST /auth/project

Purpose: Save Semrush project configuration for an account

Request:

POST /v1/integrations/semrush/auth/project
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "projectName": "Client Website SEO",
  "domain": "example.com",
  "projectId": "12345678"
}

Request Body:

Field	Type	Required	Description
projectName	String	✅	Project name (2-100 chars)
domain	String	✅	Domain without protocol or www
projectId	String	⚪	Semrush project ID

Business Logic:

1. Check if project already exists for domain
2. If exists, return existing project (201 status)
3. Fetch campaigns for project ID
4. Find Google search engine campaign
5. Store campaign_id for position tracking
6. Save project configuration

Response (201 Created):

{
  "success": true,
  "message": "Project saved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Client Website SEO",
    "domain": "example.com",
    "created_at": "2025-10-10T08:00:00Z"
  }
}

Delete Project

DELETE /auth

Purpose: Delete project configuration and all cached reports

Request:

DELETE /v1/integrations/semrush/auth?account_id=507f1f77bcf86cd799439011
Authorization: Bearer {jwt_token}

Side Effects:

• Deletes project from semrush.auth collection
• Deletes all reports from semrush.reports collection for account
• Irreversible operation

Response (200 OK):

{
  "success": true,
  "message": "Project deleted successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Client Website SEO",
    "domain": "example.com",
    "deleted_at": "2025-10-10T09:00:00Z"
  }
}

List All Projects

GET /projects

Purpose: List all Semrush projects with search and pagination

Request:

GET /v1/integrations/semrush/projects?search=seo&limit=25&page=1&new=false
Authorization: Bearer {jwt_token}

Query Parameters:

Parameter	Type	Default	Description
search	String	-	Search by project name, domain, or URL
limit	Integer	25	Items per page (1-100)
page	Integer	1	Page number
new	Boolean	false	Force refresh from API
account_id	String	-	Override account ID

Caching:

• Cache Key: domain: "global", type: "projects_list"
• TTL: 7 days
• Force Refresh: ?new=true

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "data": [
      {
        "project_id": "12345678",
        "project_name": "Client Website",
        "url": "https://example.com",
        "domain": "example.com",
        "status": "active"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 3,
      "totalItems": 75,
      "itemsPerPage": 25,
      "hasNextPage": true,
      "hasPreviousPage": false
    },
    "createdAt": "2025-10-03T08:00:00Z",
    "lastUpdate": "2025-10-03T08:00:00Z",
    "nextUpdate": "2025-10-10T08:00:00Z",
    "daysSinceUpdate": 7,
    "daysUntilUpdate": 0,
    "isStale": true
  }
}

Subscription Validation

SEO Subscription Requirement

Position tracking requires an active SEO subscription. Validation occurs automatically.

Subscription Check:

// Validates subscription with these criteria:
- plan.metadata.product_type: "seo"
- status: "active", "trialing", or "past_due"

Error Response (403 Forbidden):

{
  "success": false,
  "error_code": "SUBSCRIPTION_REQUIRED",
  "message": "SEO subscription required to access this feature"
}

Plan-Based Keyword Limits

Plan	Keyword Limit
Pro	10 keywords
Plus	20 keywords
Platinum	40 keywords
Internal (DashClicks)	Unlimited

Limit Enforcement:

• Applied to position tracking endpoint
• Pagination respects plan limits
• Keyword summary calculated on limited dataset
• Internal users bypass all limits

Campaign Management

Get Campaigns for Project

Internal API Call: getCampaigns(projectId)

Purpose: Fetch campaigns associated with a Semrush project

SOAP Request:

GET https://api.semrush.com/management/v1/projects/{projectId}/tracking/campaigns?key={API_KEY}

Response:

{
  "campaigns": [
    {
      "id": "98765432",
      "engine": "google",
      "name": "Google Campaign",
      "status": "active"
    }
  ]
}

{
  "campaigns": [
    {
      "id": "98765432",
      "engine": "google",
      "name": "Google Campaign",
      "status": "active"
    },
    {
      "id": "98765433",
      "engine": "bing",
      "name": "Bing Campaign",
      "status": "active"
    }
  ]
}

Logic:

• Finds first campaign with engine: "google"
• Stores campaign_id in project config
• Used for position tracking queries

Error Handling

Semrush API Errors

Error	Cause	Solution
ERROR 50	Invalid API key or subscription required	Check API key in Semrush dashboard
ERROR 40	Invalid project ID or resource not found	Verify project exists in Semrush
ERROR 30	Rate limit exceeded	Wait before retrying

DashClicks Errors

Error Code	HTTP Status	Description
SUBSCRIPTION_REQUIRED	403	No active SEO subscription
PROJECT_NOT_FOUND	404	Project configuration not found
INVALID_DOMAIN	400	Domain format invalid
PROJECT_EXISTS	409	Project already exists (returns existing)

Related Documentation

• Domain Analytics
• Position Tracking
• Semrush API Docs