> ## 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.

# API Authentication: Keys, Scopes, and Security Tips

> All Google API requests require an API key passed in the Authorization header. Learn how to generate keys, set scopes, and handle authentication errors.

Every request you make to the Google API must be authenticated using an API key. API keys are long-lived credentials that identify your application or integration and determine which resources it can access. You control the scope of each key at creation time, so you can issue narrowly-permissioned keys for specific use cases and limit exposure if a key is ever compromised.

## Generating an API Key

You can create as many API keys as you need directly from your Google dashboard. Each key is shown only once at creation, so make sure to copy and store it securely before closing the dialog.

<Steps>
  <Step title="Open API Key Settings">
    Log in to your Google dashboard and navigate to **Settings** in the main sidebar, then select **API Keys** from the settings menu.
  </Step>

  <Step title="Create a New Key">
    Click **New API Key** in the top-right corner of the API Keys page to open the key creation dialog.
  </Step>

  <Step title="Name Your Key">
    Enter a descriptive name for the key — for example, `Production Backend` or `Data Sync Integration`. A clear name makes it easy to identify and revoke specific keys later.
  </Step>

  <Step title="Select Scopes">
    Choose the permission scopes this key should have. Apply the principle of least privilege: only grant the scopes your integration actually needs. See the [API Key Scopes](#api-key-scopes) section below for the full list.
  </Step>

  <Step title="Copy the Key Value">
    After clicking **Create**, your new API key will be displayed once. Copy it immediately and store it in a secure location such as a secrets manager or environment variable. This value will not be shown again.
  </Step>
</Steps>

## Passing Your API Key

Include your API key on every request using the `Authorization` header with the `Bearer` scheme. The example below shows a basic authenticated request to the Users endpoint:

```bash theme={null}
curl -X GET https://api.google.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

Replace `YOUR_API_KEY` with the key value you copied during generation. Requests made without this header, or with an invalid key, will receive a `401 Unauthorized` response.

## API Key Scopes

Scopes define what an API key is permitted to do. When creating a key, select only the scopes required for your use case. You can update scopes on existing keys from the **Settings > API Keys** page at any time.

| Scope        | Access Level                    |
| ------------ | ------------------------------- |
| `read:all`   | Read all resources              |
| `write:all`  | Create and modify all resources |
| `admin`      | Full access including settings  |
| `read:data`  | Read data records only          |
| `write:data` | Create and modify data records  |
| `read:users` | Read user info only             |

Keys with `admin` scope have unrestricted access to your entire Google workspace, including sensitive settings. Reserve this scope for trusted, internal automation only.

## Authentication Errors

If your API key is missing, expired, or lacks the required scope for an endpoint, the API will return one of the following error responses:

**401 Unauthorized** — The API key is invalid, malformed, or not included in the request.

**403 Forbidden** — The API key is valid but does not have the scope required to access the requested resource.

Both error types return the same JSON envelope structure:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "request_id": "req_abc123"
  }
}
```

Use the `code` field (`UNAUTHORIZED` vs `FORBIDDEN`) to distinguish between the two cases in your error-handling logic. For `403` errors, check that the key you are using has the correct scope for the endpoint you are calling.

## Security Recommendations

<Warning>
  Never hard-code your API key directly in source code or commit it to a version control system. Always load keys from environment variables or a secrets manager at runtime. Avoid using API keys in client-side or browser-based code — any key included in frontend code is effectively public and should be treated as compromised.
</Warning>

Keep your API keys secure by following these practices:

* Store keys in environment variables (e.g., `GOOGLE_API_KEY`) and inject them at runtime.
* Use a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or 1Password for production workloads.
* Rotate keys periodically and immediately upon any suspected exposure.
* Revoke unused keys from **Settings > API Keys** to reduce your attack surface.

<Tip>
  Create a separate API key for each integration, environment (development, staging, production), or team member that needs API access. This way, you can revoke a single key without disrupting other integrations, and you get per-key visibility into usage patterns from the API Keys dashboard.
</Tip>