API Authentication: Keys and Credentials Reference

Every request to the Custom Search JSON API must be authenticated with a Google API key. The key identifies your project for quota tracking, billing, and access control. This page covers how to create a key, the two ways to pass it on each request, how to restrict it to reduce exposure, and what error responses look like when a key is missing, invalid, or revoked.

Creating an API Key

Open the Google Cloud Console

Go to console.cloud.google.com and select or create the project you want to use for search.

Enable the Custom Search API

Navigate to APIs & Services → Library, search for Custom Search API, and click Enable. The key will not work for search requests until the API is enabled on your project.

Create a credential

Navigate to APIs & Services → Credentials, click Create Credentials, and choose API key. Google generates a key immediately.

Copy and store the key securely

Copy the key value now. Treat it like a password — store it in an environment variable or secret manager, never in source code or client-side JavaScript.

Apply restrictions (recommended)

Click Edit API key and apply both an application restriction and an API restriction before your key goes to production. See Key Restrictions below.

API keys are not access tokens. They do not expire on their own and are not scoped to a user identity. Anyone who obtains your key can consume your quota. Restrict every key before using it in production.

Passing the Key on Each Request

You have two options for supplying your API key: a query parameter or an HTTP authorization header. Both are accepted on every endpoint; use whichever fits your architecture.

Option 1 — `key` Query Parameter (recommended for server-side calls)

Append key=YOUR_API_KEY to the query string. This is the most common approach and works with any HTTP client.

GET https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX&q=solar+panels

curl "https://www.googleapis.com/customsearch/v1" \
  -G \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "cx=YOUR_CX" \
  --data-urlencode "q=solar panels"

import requests

response = requests.get(
    "https://www.googleapis.com/customsearch/v1",
    params={
        "key": "YOUR_API_KEY",
        "cx":  "YOUR_CX",
        "q":   "solar panels",
    },
)
response.raise_for_status()

const url = new URL("https://www.googleapis.com/customsearch/v1");
url.searchParams.set("key", "YOUR_API_KEY");
url.searchParams.set("cx",  "YOUR_CX");
url.searchParams.set("q",   "solar panels");

const res = await fetch(url.toString());
if (!res.ok) throw new Error(`HTTP ${res.status}`);

Option 2 — `Authorization: Bearer` Header

Pass the key as an OAuth2 Bearer token in the Authorization header. Use this approach when your HTTP client or proxy framework enforces standard authorization headers and you want to keep credentials out of the URL (and therefore out of server access logs).

GET https://www.googleapis.com/customsearch/v1?cx=YOUR_CX&q=solar+panels
Authorization: Bearer YOUR_API_KEY

curl "https://www.googleapis.com/customsearch/v1" \
  -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "cx=YOUR_CX" \
  --data-urlencode "q=solar panels"

import requests

response = requests.get(
    "https://www.googleapis.com/customsearch/v1",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "cx": "YOUR_CX",
        "q":  "solar panels",
    },
)
response.raise_for_status()

const url = new URL("https://www.googleapis.com/customsearch/v1");
url.searchParams.set("cx", "YOUR_CX");
url.searchParams.set("q",  "solar panels");

const res = await fetch(url.toString(), {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);

Prefer the Authorization header over the query parameter when you control the HTTP client. URLs (including query strings) can appear in proxy logs, browser history, and CDN access logs. Headers are not logged by most intermediaries.

Do not supply both the key query parameter and an Authorization header in the same request. If both are present, the key query parameter takes precedence.

Key Restrictions

Google Cloud Console lets you attach two independent restriction layers to each API key. Apply both before you deploy.

Application Restrictions
API Restrictions

Application restrictions limit which callers can use the key. Choose the type that matches your deployment:

Restriction Type	Best For	How It Works
None	Local development only	Any caller can use the key — never use in production
HTTP referrers	Web applications	Google checks the `Referer` header against a list of allowed URL patterns (e.g., `https://example.com/*`)
IP addresses	Server-to-server	Google checks the originating IP against a CIDR allowlist
Android apps	Android clients	Restricted to apps with a matching package name and SHA-1 certificate fingerprint
iOS apps	iOS clients	Restricted to apps with a matching bundle identifier

To set a restriction: Credentials → Edit API key → Application restrictions.

HTTP referrer restrictions do not protect server-side calls — Referer headers are trivially spoofed by command-line tools. For server-to-server requests, use IP address restrictions or keep the key in a backend proxy so clients never see it.

Rotating Keys

Rotate your API key whenever:

You suspect it has been exposed (committed to a repo, logged in plaintext, etc.)
A team member who had access to the key leaves your organization
You perform a scheduled credential rotation as part of your security policy

Create the replacement key

In APIs & Services → Credentials, click Create Credentials → API key. Apply the same restrictions as the existing key before proceeding.

Deploy the new key

Update your secret manager, environment variables, and any configuration files with the new key value. Deploy the change to all services that call the API.

Verify the new key works

Make a test request with the new key and confirm you receive 200 OK. Check your Cloud Console quota dashboard to confirm queries are attributed to the new key.

Delete the old key

In Credentials, click the delete icon next to the old key. Deletion is immediate and irreversible — the old key stops working instantly.

If you are unsure whether the old key is still in use anywhere, disable it instead of deleting it first. A disabled key returns 401 errors, making it easy to identify any missed references in your logs before you delete permanently.

Error Responses for Authentication Failures

When a request fails due to a missing, invalid, restricted, or revoked API key, the API returns a structured JSON error body. All authentication errors carry an error object at the top level.

Missing Key — `400 Bad Request`

Omitting the key parameter entirely returns a 400:

{
  "error": {
    "code": 400,
    "message": "API key not provided. Please provide an API key.",
    "status": "INVALID_ARGUMENT"
  }
}

Invalid Key — `401 Unauthorized`

A key that does not exist or has been deleted returns a 401:

{
  "error": {
    "code": 401,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "UNAUTHENTICATED"
  }
}

Key Restricted — `403 Forbidden`

A key that exists but does not have permission to call this API (API restriction not met) or that is being called from a disallowed referrer or IP (application restriction not met) returns a 403:

{
  "error": {
    "code": 403,
    "message": "Requests from this Android client application <package.name> are blocked.",
    "status": "PERMISSION_DENIED"
  }
}

Other 403 messages you may see

API not enabled on project:

{
  "error": {
    "code": 403,
    "message": "Custom Search API has not been used in project 123456789 before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/customsearch.googleapis.com/overview?project=123456789 then retry.",
    "status": "PERMISSION_DENIED"
  }
}

Daily 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"
  }
}

Referrer blocked:

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

Handling Authentication Errors in Code

Check the HTTP status code first, then inspect error.status for granular handling:

import requests

def search(query: str, api_key: str, cx: str) -> dict:
    resp = requests.get(
        "https://www.googleapis.com/customsearch/v1",
        params={"key": api_key, "cx": cx, "q": query},
    )

    if resp.status_code == 401:
        raise ValueError("Invalid API key — check your credentials.")
    if resp.status_code == 403:
        error = resp.json().get("error", {})
        if error.get("status") == "RESOURCE_EXHAUSTED":
            raise RuntimeError("Daily quota exceeded — retry tomorrow or upgrade.")
        raise PermissionError(f"Access denied: {error.get('message')}")

    resp.raise_for_status()
    return resp.json()

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

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

  if (res.status === 401) {
    throw new Error("Invalid API key — check your credentials.");
  }
  if (res.status === 403) {
    const body = await res.json();
    const status = body?.error?.status;
    if (status === "RESOURCE_EXHAUSTED") {
      throw new Error("Daily quota exceeded — retry tomorrow or upgrade.");
    }
    throw new Error(`Access denied: ${body?.error?.message}`);
  }

  if (!res.ok) throw new Error(`Unexpected error: HTTP ${res.status}`);
  return res.json();
}

API Overview

Base URL, required parameters, response shape, and a minimal working example.

Error Codes

Full reference for every HTTP status code the API returns, with resolution steps.

​Creating an API Key

​Passing the Key on Each Request

​Option 1 — key Query Parameter (recommended for server-side calls)

​Option 2 — Authorization: Bearer Header

​Key Restrictions

​Rotating Keys

​Error Responses for Authentication Failures

​Missing Key — 400 Bad Request

​Invalid Key — 401 Unauthorized

​Key Restricted — 403 Forbidden

​Handling Authentication Errors in Code

​Related Pages

API Overview

Error Codes

Creating an API Key

Passing the Key on Each Request

Option 1 — `key` Query Parameter (recommended for server-side calls)

Option 2 — `Authorization: Bearer` Header

Key Restrictions

Rotating Keys

Error Responses for Authentication Failures

Missing Key — `400 Bad Request`

Invalid Key — `401 Unauthorized`

Key Restricted — `403 Forbidden`

Handling Authentication Errors in Code

Related Pages