> For the complete documentation index, see [llms.txt](https://docs.adpage.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adpage.io/optimize-your-setup/connect-google-cloud-service-account.md).

# Connect Google Cloud Service account

Use Firestore, BigQuery and other Google Cloud services from your GTM server container by connecting a Service Account from your own Google Cloud project.

### When do you need this?

Some server-side tags and variables read from or write to Google Cloud. Common examples:

* **Firestore Lookup** variable — enrich events with data stored in Firestore, for example to build an extra conversion action based on customer or order data.
* **Firestore Writer** tags — store event data in Firestore.
* **BigQuery** tags — stream tracking data into your own BigQuery dataset.

These tags authenticate with the Google credentials of the server container. Because your data lives in **your own** Google Cloud project, you create a Service Account in that project and connect it to your AdPage container. AdPage does not hand out a shared Service Account that you grant access to: you stay owner of the account, the permissions and the key.

{% hint style="info" %}
In the AdPage dashboard this setting is called **Google BigQuery**, but the Service Account you upload there is used for all Google Cloud access from your server container, Firestore included.
{% endhint %}

### Step 1: create the Service Account

{% stepper %}
{% step %}

#### Open IAM in your Google Cloud project

In the [Google Cloud Console](https://console.cloud.google.com/), select the project that contains your Firestore database (or BigQuery dataset) and go to **IAM & Admin → Service Accounts**.
{% endstep %}

{% step %}

#### Create the account

Click **Create service account** and give it a recognisable name, for example `adpage-sgtm`.
{% endstep %}

{% step %}

#### Grant the roles

Give the account only the roles your tags need:

| Use case                          | Role                                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Firestore Lookup (read only)      | `Cloud Datastore Viewer` (`roles/datastore.viewer`)                                                     |
| Firestore Writer (read and write) | `Cloud Datastore User` (`roles/datastore.user`)                                                         |
| BigQuery                          | `BigQuery Data Editor` (`roles/bigquery.dataEditor`) and `BigQuery Job User` (`roles/bigquery.jobUser`) |

Need both Firestore and BigQuery? Give the **same** Service Account all the roles you need. A container holds one Service Account at a time (see [Things to know](#things-to-know)).
{% endstep %}

{% step %}

#### Create a JSON key

Open the Service Account, go to **Keys → Add key → Create new key**, choose **JSON** and download the file.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Can't create a key? Your organisation may enforce the policy `iam.disableServiceAccountKeyCreation`. Ask your Google Cloud administrator for an exception for this project.
{% endhint %}

### Step 2: connect the Service Account in AdPage

{% stepper %}
{% step %}

#### Open the container settings

In the [AdPage dashboard](https://data.adpage.io), go to **Containers**, open your container and click **Settings**.
{% endstep %}

{% step %}

#### Upload the JSON file

In the menu on the left, choose **Google BigQuery**. Drag the JSON file into the upload area (or click to select it) and click **Save**.

<figure><img src="https://1274044937-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA65KwL1NwewlJbtCXsXd%2Fuploads%2FEqQT6eJORlBQC7tPnEIw%2Fdata-streams-bigquery-export-en.webp?alt=media" alt="BigQuery export screen with the Service Account upload area"><figcaption><p>BigQuery export: upload the JSON key of your Service Account.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Check the status

When the upload succeeds, the section shows that a Service Account is connected.
{% endstep %}
{% endstepper %}

{% hint style="danger" %}
The JSON file contains a private key. Upload it only in the AdPage dashboard and do not send it by email or chat. Delete the downloaded file once it has been uploaded.
{% endhint %}

### Step 3: use it in your GTM server container

For a **Firestore Lookup** variable:

1. In your GTM server container, go to **Variables → New** and choose **Firestore Lookup**.
2. Enter the collection path and the document path or query.
3. Under **Advanced**, enable **Override Project ID** and enter the ID of the Google Cloud project that contains your Firestore database. Without this, the variable looks in the project the server container runs in, not in yours.

The same applies to Firestore and BigQuery tags from the Community Template Gallery: always enter your own project ID.

{% hint style="success" %}
Test it in the GTM Preview Mode. Open a request that uses the variable and check that it returns a value. A permission error usually means a role is missing or the project ID is wrong.
{% endhint %}

### Things to know

* **One Service Account per container.** Uploading a new JSON file replaces the previous one. If you use the container for both BigQuery and Firestore, use one Service Account with all the roles it needs.
* **Rotating the key.** Create a new key in Google Cloud, upload it in AdPage, check your tags in Preview Mode and only then delete the old key in Google Cloud.
* **Revoking access.** Deleting the key or the Service Account in Google Cloud stops access immediately. Tags that depend on it will then fail.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.adpage.io/optimize-your-setup/connect-google-cloud-service-account.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.