Authenticate Requests to the Google Search API

Every request to the Google Custom Search JSON API must include a valid API key. The key identifies your project to Google, enforces quota limits, and lets you monitor usage in the Cloud Console. This page walks you through creating a key, attaching it to requests, locking it down so only your code can use it, and recovering gracefully when authentication fails.

Create an API key

API keys live inside Google Cloud projects. You need a project before you can create a key.

Pass the key in a request

The Custom Search API accepts your key in two ways. Both are equally valid; use whichever fits your stack.

Option 1 — `key` query parameter (most common)

Append key=YOUR_API_KEY to the query string. This is the approach shown in Google’s own documentation and in most client libraries.

curl
Python
JavaScript (fetch)

curl "https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX&q=climate+change"

import os
import requests

response = requests.get(
    "https://www.googleapis.com/customsearch/v1",
    params={
        "key": os.environ["GOOGLE_API_KEY"],
        "cx": os.environ["GOOGLE_CX"],
        "q": "climate change",
    },
)
response.raise_for_status()
print(response.json()["searchInformation"]["totalResults"])

const API_KEY = process.env.GOOGLE_API_KEY;  // Never hard-code this
const CX = process.env.GOOGLE_CX;

const url = new URL("https://www.googleapis.com/customsearch/v1");
url.searchParams.set("key", API_KEY);
url.searchParams.set("cx", CX);
url.searchParams.set("q", "climate change");

const response = await fetch(url.toString());

if (!response.ok) {
  const err = await response.json();
  throw new Error(`Search failed: ${err.error.message}`);
}

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

Option 2 — `Authorization` header

If you prefer to keep credentials out of the URL (useful when URLs are logged by proxies or servers), pass the key as a Bearer token in the Authorization header.

curl
Python
JavaScript (fetch)

curl "https://www.googleapis.com/customsearch/v1?cx=YOUR_CX&q=climate+change" \
  -H "Authorization: Bearer YOUR_API_KEY"

import os
import requests

response = requests.get(
    "https://www.googleapis.com/customsearch/v1",
    params={
        "cx": os.environ["GOOGLE_CX"],
        "q": "climate change",
    },
    headers={
        "Authorization": f"Bearer {os.environ['GOOGLE_API_KEY']}",
    },
)
response.raise_for_status()

const response = await fetch(
  `https://www.googleapis.com/customsearch/v1?cx=${process.env.GOOGLE_CX}&q=climate+change`,
  {
    headers: {
      Authorization: `Bearer ${process.env.GOOGLE_API_KEY}`,
    },
  }
);

The Authorization: Bearer approach is identical in security to the key query parameter for API keys. Neither method encrypts the key beyond TLS — both are safe only over HTTPS, which the Custom Search API enforces.

Restrict your API key

Key restrictions are your primary defense against unauthorized use. Apply at least one restriction to every production key.

HTTP referrer restrictions

Limit the key to requests that originate from specific URLs. Ideal for browser-based integrations where you control the domain.

IP address restrictions

Limit the key to one or more server IP addresses. Ideal for server-to-server API calls where your server has a static IP.

API restrictions

Limit the key to specific Google APIs (e.g., Custom Search API only). Always combine this with an application restriction.

Per-key quota limits

Set a maximum daily or per-minute quota in Cloud Console to cap spend even if the key is misused.

Set HTTP referrer restrictions

In APIs & Services → Credentials, open your key and scroll to Application restrictions:

Select HTTP referrers (websites).
Add your allowed origins, for example:
- https://www.example.com/* — all pages on your site
- https://app.example.com/search* — a specific path
Click Save.

HTTP referrer restrictions rely on the Referer header, which can be spoofed in server-side contexts. Use IP address restrictions for backend services instead.

Set IP address restrictions

Select IP addresses (web servers, cron jobs, etc.).
Enter your server’s IPv4 or IPv6 address (e.g., 203.0.113.42 or 203.0.113.0/24 for a range).
Click Save.

Best practices for key security

Use environment variables, never source code

Hard-coded keys in source files are the most common cause of credential leaks. Store keys in environment variables or a secrets manager (Google Secret Manager, AWS Secrets Manager, HashiCorp Vault) and read them at runtime.

import os
API_KEY = os.environ["GOOGLE_API_KEY"]  # ✅ Safe
API_KEY = "AIzaSy..."                   # ❌ Never do this

Add .env files to .gitignore

If you use a .env file for local development, make sure it’s listed in .gitignore before your first commit.

# .gitignore
.env
.env.local
.env.*.local

Use .env.example (with placeholder values) to document required variables for teammates.

Rotate keys immediately if exposed

If you accidentally commit a key or expose it in logs:

Go to APIs & Services → Credentials.
Delete the compromised key.
Create a new key and apply restrictions immediately.
Update all services using the old key.

Check your Cloud Console quota dashboard for unusual usage spikes that might indicate the key was already used.

Create separate keys per environment

Use distinct keys for development, staging, and production. This lets you rotate or delete a key in one environment without affecting others, and gives you per-environment visibility in usage reports.

Audit usage regularly

In APIs & Services → Metrics, review request volume, error rates, and latency per API key. Set up budget alerts in Cloud Billing to get notified before unexpected spend accumulates.

Authentication error responses

When authentication fails, the API returns a JSON error body alongside an HTTP error status code. Parse error.code and error.message to determine the cause.

401 — Invalid credentials

The API key is malformed, deleted, or belongs to a different project.

{
  "error": {
    "code": 401,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com"
      }
    ]
  }
}

How to fix: Verify the key exists in your Cloud Console credentials page, that it’s for the correct project, and that the Custom Search API is enabled on that project.

403 — Quota exceeded or key restriction mismatch

A 403 can mean two different things:

Quota exceeded
Key restriction mismatch

You’ve exhausted the 100 free queries/day on the free tier. The reason field will be RATE_LIMIT_EXCEEDED or QUOTA_EXCEEDED.

{
  "error": {
    "code": 403,
    "message": "Quota exceeded for quota metric 'customsearch.googleapis.com/requests' and limit 'Queries per day' of service 'customsearch.googleapis.com'.",
    "status": "RESOURCE_EXHAUSTED"
  }
}

How to fix: Enable billing on your project and purchase additional quota (up to 10,000 queries/day) in the Cloud Console.

The request originated from an IP address or HTTP referrer that doesn’t match your key’s restrictions.

{
  "error": {
    "code": 403,
    "message": "Requests from referer <empty> are blocked.",
    "status": "PERMISSION_DENIED"
  }
}

How to fix: Update the key’s application restrictions to include the IP or referrer from which the request originated, or use an unrestricted key for testing.

Handle errors in code

Always check the status code before accessing response data:

import os
import requests

def search(query: str) -> dict:
    response = requests.get(
        "https://www.googleapis.com/customsearch/v1",
        params={
            "key": os.environ["GOOGLE_API_KEY"],
            "cx": os.environ["GOOGLE_CX"],
            "q": query,
        },
    )

    if response.status_code == 401:
        raise PermissionError("Invalid API key — check GOOGLE_API_KEY.")
    if response.status_code == 403:
        data = response.json()
        raise PermissionError(f"Access denied: {data['error']['message']}")
    if response.status_code == 429:
        raise RuntimeError("Rate limited — implement exponential back-off.")

    response.raise_for_status()  # Catch any other 4xx/5xx
    return response.json()

async function search(query) {
  const url = new URL("https://www.googleapis.com/customsearch/v1");
  url.searchParams.set("key", process.env.GOOGLE_API_KEY);
  url.searchParams.set("cx", process.env.GOOGLE_CX);
  url.searchParams.set("q", query);

  const response = await fetch(url.toString());
  const data = await response.json();

  if (!response.ok) {
    const { code, message } = data.error;
    if (code === 401) throw new Error(`Invalid API key: ${message}`);
    if (code === 403) throw new Error(`Forbidden: ${message}`);
    if (code === 429) throw new Error(`Rate limited: ${message}`);
    throw new Error(`API error ${code}: ${message}`);
  }

  return data;
}

Get Started

Core Concepts

Search Features

Guides

Help

Authenticate Requests to the Google Search API

Create an API key

Pass the key in a request

Option 1 — `key` query parameter (most common)

Option 2 — `Authorization` header

Restrict your API key

HTTP referrer restrictions

IP address restrictions

API restrictions

Per-key quota limits

Set HTTP referrer restrictions

Set IP address restrictions

Best practices for key security

Authentication error responses

401 — Invalid credentials

403 — Quota exceeded or key restriction mismatch

Handle errors in code

Next steps

Quick Start

Query Parameters

​Create an API key

​Pass the key in a request

​Option 1 — key query parameter (most common)

​Option 2 — Authorization header

​Restrict your API key

HTTP referrer restrictions

IP address restrictions

API restrictions

Per-key quota limits

​Set HTTP referrer restrictions

​Set IP address restrictions

​Best practices for key security

​Authentication error responses

​401 — Invalid credentials

​403 — Quota exceeded or key restriction mismatch

​Handle errors in code

​Next steps

Quick Start

Query Parameters

Create an API key

Pass the key in a request

Option 1 — `key` query parameter (most common)

Option 2 — `Authorization` header

Restrict your API key

Set HTTP referrer restrictions

Set IP address restrictions

Best practices for key security

Authentication error responses

401 — Invalid credentials

403 — Quota exceeded or key restriction mismatch

Handle errors in code

Next steps