> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newport.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating with the Google API: Keys and Security

> Learn how to generate and use API keys to authenticate with the Google API, handle token errors, and keep your credentials secure.

Every request you make to the Google API must include a valid API key so the platform can identify your application and enforce the correct permissions. API keys are long-lived tokens tied to your workspace, and you can create as many as you need — one per app, script, or integration — so that each one can be scoped, monitored, and revoked independently without affecting the others.

## Generating an API Key

<Steps>
  <Step title="Open the API Keys Panel">
    Log in to your workspace and navigate to **Settings → API Keys** in the left sidebar.
  </Step>

  <Step title="Create a New Key">
    Click the **+ New API Key** button in the top-right corner of the panel.
  </Step>

  <Step title="Name Your Key">
    Give the key a descriptive name that reflects its purpose — for example, `production-backend`, `ci-pipeline`, or `local-dev`. A clear name makes it easier to audit and revoke specific keys later.
  </Step>

  <Step title="Select Scopes">
    Choose the permission scopes this key should have. Applying the minimum scopes necessary reduces risk if the key is ever compromised. See the [Key Scopes](#key-scopes) section below for a full breakdown.
  </Step>

  <Step title="Copy and Store the Key Securely">
    Click **Generate Key**. Your new API key is displayed **only once** — copy it immediately and store it in a secrets manager, password vault, or environment variable. If you lose it, you'll need to generate a new one.
  </Step>
</Steps>

## Using Your API Key

Pass your API key in the `Authorization` header using the `Bearer` scheme on every request. The examples below show the same request across three common tools.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api.google.com/v1/users \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        'https://api.google.com/v1/users',
        headers={'Authorization': 'Bearer YOUR_API_KEY'}
    )
    print(response.json())
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.google.com/v1/users', {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    const data = await response.json();
    ```
  </Tab>
</Tabs>

Replace `YOUR_API_KEY` with the key you copied from the dashboard. All API endpoints are served over HTTPS — plain HTTP requests are rejected.

## Key Scopes

When generating an API key you select one or more scopes that define exactly what that key can do. Granting only the scopes your integration actually needs limits the blast radius of a compromised credential.

| Scope       | Access Granted                                                                         |
| ----------- | -------------------------------------------------------------------------------------- |
| `read:all`  | Read access to all resources (users, projects, records, settings) across the workspace |
| `write:all` | Create and update access to all non-administrative resources                           |
| `admin`     | Full access including team management, billing, and API key administration             |

<Info>
  The `admin` scope encompasses all `read:all` and `write:all` permissions, so you don't need to stack scopes. Reserve `admin` keys for trusted internal systems and human operators.
</Info>

## Security Best Practices

<Warning>
  **Never commit API keys to source control.** Storing a key in a Git repository — even a private one — is one of the most common causes of credential exposure. Automated scanners actively crawl public and private repos for leaked secrets.

  Follow these practices to keep your keys safe:

  * **Use environment variables.** Store keys in `.env` files (excluded via `.gitignore`) or your deployment platform's secret store (e.g., GitHub Secrets, AWS Secrets Manager, Doppler).
  * **Rotate keys regularly.** Generate a replacement key, update your application, then revoke the old one — ideally on a 90-day cycle or immediately after any team member departure.
  * **Scope keys minimally.** A key used only for reading data should never have `write:all` or `admin` permissions.
  * **Revoke unused keys.** If a key hasn't been used in 30+ days, delete it from **Settings → API Keys**.
</Warning>

## Authentication Errors

If your API requests return an error status, the table below explains the most likely cause and how to fix it.

| Status Code | Error                 | Meaning                                                         | Fix                                                                                                                                                                |
| ----------- | --------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401`       | **Unauthorized**      | The API key is missing, malformed, or has been revoked          | Double-check the `Authorization: Bearer ...` header is present and the key is copied correctly with no whitespace                                                  |
| `403`       | **Forbidden**         | The key is valid but lacks the scope required for this endpoint | Open **Settings → API Keys**, edit the key, and add the necessary scope (e.g., `write:all` for POST/PATCH requests)                                                |
| `429`       | **Too Many Requests** | Your key has exceeded its rate limit for the current window     | Back off and retry after the number of seconds indicated in the `Retry-After` response header; review the [Rate Limits](/api/rate-limits) page for per-plan limits |