Authentication

The SerpWatch API uses Bearer token authentication. All API requests must include your API key in the Authorization header.

Overview

Authentication is required for all API endpoints. The SerpWatch API uses Bearer token authentication — simply include your API key in the Authorization header of each request.

Getting Your API Key

API access requires an active subscription. Complete the following steps to generate your API key:

Create Account and Subscribe

Access Account Settings

Locate your user avatar (displaying your initials) in the bottom-right corner of the dashboard. Click the avatar and select Account Settings.

Open API Details

Within Account Settings, navigate to the API Details section.

Generate Your Key

Click Generate API Key. Copy the key and store it in a secure location.

Important

Keep your API key confidential. Store it securely using a password manager or environment variable. If your key is compromised, generate a new one immediately.

Using Your API Key

Include your API key in the Authorization header of every request:

curl -X GET "https://engine.v2.serpwatch.io/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://engine.v2.serpwatch.io/api/v1/users/me",
    headers=headers
)

print(response.json())

const response = await fetch(
  "https://engine.v2.serpwatch.io/api/v1/users/me",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    }
  }
);

const data = await response.json();
console.log(data);

Authentication Errors

The API returns specific error codes for authentication failures:

Status Code	Error	Description
`401`	Unauthorized	Missing or invalid API key. Check that the Authorization header is correct.
`403`	Forbidden	Valid API key but insufficient permissions or rate limit exceeded.

{
  "detail": "Could not validate credentials"
}

Security Best Practices

Keep Your API Key Secure

Your API key provides full access to your account. Treat it like a password.

Use environment variables - Never hardcode API keys in your source code.
Don't expose in client-side code - API requests should be made from your backend server, not from browser JavaScript.
Rotate keys periodically - Contact support if you need to regenerate your API key.
Use HTTPS only - The API only accepts connections over HTTPS.
Monitor usage - Check your usage regularly for unexpected activity.

# Store in .env file (add to .gitignore)
SERPWATCH_API_KEY=your_api_key_here

# Load in your shell
export $(cat .env | xargs)

# Use in curl commands
curl -H "Authorization: Bearer $SERPWATCH_API_KEY" ...

import os
from dotenv import load_dotenv

# Load from .env file
load_dotenv()

# Access the key
API_KEY = os.environ.get("SERPWATCH_API_KEY")

if not API_KEY:
    raise ValueError("SERPWATCH_API_KEY not set")

// Load from environment
require('dotenv').config();

const API_KEY = process.env.SERPWATCH_API_KEY;

if (!API_KEY) {
  throw new Error("SERPWATCH_API_KEY not set");
}