# Connecting Google with a Service Account

Set up a Google Cloud service account to connect Google Analytics, Search Console, Tag Manager, and Google Ads with scoped access and your own API quota.

A **service account** is a Google account for software instead of a person. It has its own email address ending in `iam.gserviceaccount.com`, and you grant it access to your Google properties the same way you'd add a colleague: by adding that email as a user with the role you choose.

This is **the only way to connect Google Ads**, and the recommended way to connect the other Google services for agencies and technical users. Compared to "Connect with Google" (OAuth), a service account:

- **Scopes access precisely.** The connection can only see the exact GA4 properties, Search Console sites, Tag Manager containers, and Google Ads accounts you share with it - nothing else from anyone's personal account.
- **Isn't tied to a person.** OAuth connections break when the person who signed in leaves the team, changes their password, or revokes app access. A service account keeps working.
- **Uses your own API quota.** OAuth requests go through the shared AI Data Stream application, so heavy usage shares one pool. Service account requests are attributed to *your* Google Cloud project, with your own rate limits.
- **Reuses one setup everywhere.** Create the service account once, then use the same JSON key for GA4, Search Console, Tag Manager, and Google Ads across all your properties. Agencies can create one per client for hard separation.

The trade-off: about 15 minutes of one-time setup in Google Cloud Console. This guide walks through every step.

> **Google Ads is service account only.** Google permanently pairs a Google Cloud project with the first Google Ads developer token used with it, so a developer token can only be used from a Cloud project it is paired with - yours. That rules out connecting Ads through a shared sign-in, and it has a real upside: your token stays tied to your own project rather than being captured by ours. You still need a [developer token](/docs/connecting-data-sources/#google-ads) on every call, whichever way you authenticate.

## How It Works

The whole setup is three ideas:

1. **Create** a service account in a Google Cloud project you own. Google gives you a JSON key file - the service account's credentials.
2. **Share** your properties with the service account's email address (found in the JSON as `client_email`), using each platform's normal user management.
3. **Paste** the JSON into AI Data Stream when adding a connection. We fetch the properties the service account can see, you pick one, done.

The service account can only read what you've explicitly shared, and every credential is stored encrypted.

## Step 1: Create a Google Cloud Project

If you already have a Google Cloud project, you can reuse it and skip ahead.

1. Go to [console.cloud.google.com](https://console.cloud.google.com/)
2. Sign in with any Google account (this account only *owns* the project; it doesn't need access to your analytics data)
3. Click the project selector in the top bar, then **New project**
4. Name it something recognizable, like `aidata-connections`, and click **Create**
5. Make sure the new project is selected in the top bar before continuing

All the APIs used here are free - there are no per-call charges for any of these connections. Depending on your account, Google may still ask you to link a billing account when you create a project (organisation and Workspace accounts often do). Linking one doesn't mean you'll be billed for these APIs.

![Google Cloud Console New Project form with a project name entered and the generated project ID shown below it](/images/docs/service-account/cloud-new-project.png)

The name is only a label - pick whatever you'll recognise later. If your account belongs to a Google Cloud organisation you'll also be asked for a parent; a personal account leaves those fields empty.

## Step 2: Enable the APIs

APIs must be enabled **in the same project as the service account**. Only enable the ones matching the connections you plan to use:

| Connection | API to enable |
|------------|---------------|
| Google Analytics 4 | [Google Analytics Data API](https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com) **and** [Google Analytics Admin API](https://console.cloud.google.com/apis/library/analyticsadmin.googleapis.com) |
| Google Search Console | [Google Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com) |
| Google Tag Manager | [Tag Manager API](https://console.cloud.google.com/apis/library/tagmanager.googleapis.com) |
| Google Ads | [Google Ads API](https://console.cloud.google.com/apis/library/googleads.googleapis.com) |

For each one:

1. Open the link above (or go to **APIs & Services → Library** and search for the name)
2. Check the correct project is selected in the top bar
3. Click **Enable**

GA4 needs both APIs: the Data API answers reporting queries, and the Admin API lists your properties and handles annotations.

![Google Cloud API Library search results for "google ads api", with the Google Ads API result among them](/images/docs/service-account/cloud-api-library-search.png)

Open the API you need from the results, then click **Enable**:

![The Google Ads API product page in Google Cloud with the Enable button](/images/docs/service-account/cloud-enable-google-ads-api.png)

## Step 3: Create the Service Account

1. In the Cloud Console, go to **APIs & Services → Credentials** and click **Create credentials → Service account** (**IAM & Admin → Service Accounts → Create service account** gets you to the same form)
2. Fill in the form that opens
3. Give it a name like `aidata-stream` - the generated email below the name field is the address you'll be sharing your properties with
4. Click **Create and continue**
5. **Skip both optional steps** ("Grant this service account access to project" and "Grant users access") - the service account needs **no roles** in your Cloud project. Its access comes entirely from the sharing you'll do in Step 5.
6. Click **Done**

![The Create credentials menu in Google Cloud open, with the Service account option listed under API key and OAuth client ID](/images/docs/service-account/cloud-create-service-account.png)

## Step 4: Create a JSON Key

1. On the Service Accounts page, click the account you just created
2. Open the **Keys** tab
3. Click **Add key → Create new key**
4. Choose **JSON** and click **Create**

A `.json` file downloads to your computer. This file *is* the service account's password - anyone holding it can read whatever data you share with the service account, so store it like any other credential and don't commit it to a code repository.

Open the file in a text editor and find the `client_email` field:

```json
{
  "type": "service_account",
  "project_id": "aidata-connections",
  "client_email": "aidata-stream@aidata-connections.iam.gserviceaccount.com",
  ...
}
```

That email address is what you'll add to each platform in the next step.

> **"Key creation is disabled" error?** Newer Google Cloud organizations block service account keys by default (the `iam.disableServiceAccountKeyCreation` policy). Your organization administrator can allow key creation for this project. Personal Google accounts aren't affected.

![The service account Keys tab with the Add key menu open showing Create new key](/images/docs/service-account/cloud-create-json-key.png)

## Step 5: Grant Access on Each Platform

Add the `client_email` address as a user wherever you want the connection to reach. AI Data Stream is read-only, so the lowest read role is enough everywhere.

### Google Analytics 4

1. In [Google Analytics](https://analytics.google.com/), open the property and go to **Admin**
2. In the **Property** column, click **Property access management**
3. Click **+** → **Add users**
4. Enter the service account email
5. Untick **Notify new users by email** (a service account can't receive mail)
6. Choose the **Viewer** role and click **Add**

Viewer covers everything the AI needs for analysis. Choose **Editor** only if you want AI Data Stream's [annotations](/docs/annotations/) synced into GA4 as native annotations - creating those requires edit rights.

### Google Search Console

You must be an **Owner** of the Search Console property to add users.

1. In [Search Console](https://search.google.com/search-console), select the property
2. Go to **Settings → Users and permissions**
3. Click **Add user**
4. Enter the service account email
5. Choose **Full** permission and click **Add**

Full is still read-only for our purposes and keeps every feature working, including URL inspection. **Restricted** also works if you only need search performance data.

### Google Tag Manager

1. In [Tag Manager](https://tagmanager.google.com/), go to **Admin**
2. In the **Account** column, click **User Management**
3. Click **+** → **Add users**
4. Enter the service account email
5. Set account permission to **User**
6. Under container permissions, give **Read** access to the containers you want to connect
7. Click **Invite** - service accounts are added without needing to accept

### Google Ads

Google Ads accepts service accounts as direct users - no email invitation needs accepting.

1. In [Google Ads](https://ads.google.com/), open the ad account and go to **Admin → Access and security**
2. On the **Users** tab, click **+**
3. Enter the service account email
4. Select the **Read only** access level - it covers all reporting
5. Click **Add account**

![Google Ads "Invite others" form with a service account email entered and the access level options highlighted](/images/docs/service-account/google-ads-sa-add-access.png)

*Image from the [Google Ads API documentation](https://developers.google.com/google-ads/api/docs/oauth/service-accounts), used under CC BY 4.0.*

Add the service account to the **ad account itself**, not only to the manager account above it - manager accounts can't be reported on. Once it has access, we list the accounts it can reach and you pick from a dropdown, so you don't need to hunt for the customer ID yourself.

Remember: you still need a [developer token with Basic Access](/docs/connecting-data-sources/#google-ads) when you create the connection.

## Step 6: Connect in AI Data Stream

1. Go to your property and click **Add Connection**
2. Select the connection type (Google Analytics 4, Search Console, Tag Manager, or Google Ads)
3. Choose **Service Account** as the authentication method - Google Ads skips this step, as it has no other method
4. Open the downloaded `.json` file in a text editor, copy the **entire contents** (including the outer `{ }` braces), and paste it into the credentials field
5. For Google Ads only: also enter your **developer token**. Listing accounts is itself an API call, so nothing appears until the token is in
6. We list every property the service account can see - select one and click **Add Connection**

Repeat for each connection type. The same JSON works for all of them, as long as the matching API is enabled and access has been granted.

## Revoking Access

You're in control at both ends, and can revoke at any time:

- **Remove one platform:** delete the service account's user entry in GA4 / Search Console / Tag Manager / Google Ads. The connection loses access to that platform immediately.
- **Kill the key:** in Cloud Console, open the service account's **Keys** tab and delete the key. Every connection using that JSON stops working.
- **Delete the connection:** removing the connection in AI Data Stream deletes the stored credentials from our side.

## Troubleshooting

**"No properties found" when connecting**

- The service account hasn't been granted access yet, or was granted on the wrong account - double-check you added the exact `client_email` from the JSON
- Access can take a few minutes to propagate after adding the user - wait and try again
- For GA4, make sure the **Google Analytics Admin API** is enabled (it's the one that lists properties)
- For Google Ads, check the developer token is filled in - we can't list anything without it. Manager accounts themselves never appear in the list: reports can't run against them, only against the ad accounts beneath them

**"Invalid JSON format"**

- Paste the complete file contents, from the opening `{` to the closing `}` - a partial paste or just the private key won't validate

**Error mentioning "API has not been used in project ... or it is disabled"**

- The API for that connection isn't enabled in the service account's own project - see [Step 2](#step-2-enable-the-apis). The error message includes a direct link to the right page.

**"Permission denied" on a specific query**

- The service account's role was reduced or removed on the platform side - re-check its user entry there

**Google Ads errors about the developer token**

- Service accounts don't change the token requirements: a test-access token can't read live campaign data. See the [developer token guide](/docs/connecting-data-sources/#google-ads) for getting Basic Access.

**Google Ads `DEVELOPER_TOKEN_PROHIBITED`**

- Your developer token and the Cloud project holding the service account aren't paired. A token is permanently bound to the first Cloud project it is used from, so use the service account in that same project - or, if the token has never been used, this first call is what pairs them.

## Next Steps

- [Connecting Data Sources](/docs/connecting-data-sources/) - all connection types, and the Google Ads developer token walkthrough
- [Start a conversation with your data](/docs/using-ai-chat/)
- [Understanding BYOK](/docs/byok-explained/) - the same bring-your-own-credentials idea, applied to AI providers