Create a Google service account for the Data Manager API

A service account is a Google Cloud identity that a program uses instead of a person. GTM4WP signs its requests to the Google Data Manager API with one, so creating it is the first step of the Data Manager setup. This page covers creating the account, giving it access to your Google Analytics 4 property and uploading its key file to GTM4WP.

New in 2.1.0. The Google service accounts section is experimental.
GTM4WP 2.0.x: there is no Google service accounts section.

Creating the service account in Google Cloud

You need a Google Cloud project. An existing one works, or you can create a new one for this site. These steps were checked against the Google Cloud console and Google Analytics in October 2026.

Open the Google Cloud console and select the project.
Enable the API: open the Data Manager API in the API Library and press Enable. If the page shows Manage and “API Enabled”, it is already on. The project does not need a billing account to enable it.
Create the account: open Service Accounts (IAM & Admin → Service Accounts) and press Create service account. Enter a name you will recognize later, for example “GTM4WP refunds”. The service account ID is filled in from it. Press Create and continue, which creates the account. The next step, Permissions (optional), grants the account roles in the project. Google’s setup guide asks for the Service Usage Consumer role there. In our tests, an account calling the API from its own project worked without any role, so you can skip it. Granting it does no harm, because it only lets the account use the APIs enabled in this project. Press Done to finish.
Create its key: open the new service account on the Service Accounts page, go to the Keys tab and choose Add key → Create new key. Keep the key type on JSON, because GTM4WP does not accept the P12 type, and press Create. The browser downloads the key file. You cannot download it again later, so store it somewhere safe and never in a public code repository: Google automatically disables keys it finds there.
Copy the email address of the service account. It ends in .iam.gserviceaccount.com.

Google describes these steps in its own guides on setting up access to the Data Manager API and on creating service account keys. If Google Cloud refuses to create a key, an organization policy (iam.disableServiceAccountKeyCreation) blocks key creation in your Google Cloud organization. Google enforces it by default for organizations created on or after 3 May 2024. An administrator of the organization can allow it for this project on the Organization Policies page.

Giving it access to Google Analytics

In Google Analytics, open Admin and, under Property settings → Property, Property access management of the property you want to send events to. Google’s help article on adding Analytics users shows the screens.
Press + and choose Add users. Enter the email address of the service account, then change the role from the preselected Viewer to Editor: Google requires Editor or Administrator for sending events. Leave the data restrictions unticked. “Notify new users by email” does not matter, because a service account has no mailbox. Press Add.

Give the account access to this property and nothing else. It does not need more, and the less it can reach, the less harm a leaked key can do.

Uploading the key file

Open the GTM4WP settings and go to the Google service accounts section. Choose the JSON key file under Add a service account and upload it unchanged. The label is optional: without one the account is listed by its email address, and you can rename it later. GTM4WP accepts only a Google Cloud service account key file of at most 16 KB and refuses anything else before it is stored.

Press Test next to the account. GTM4WP asks Google for an access token with the key, which proves that the key is valid and active, and the status changes from “Not tested yet” to “Working”. This test does not check the access to Google Analytics. The Test button of a Data Manager destination does that, so add the destination next.

You can store several accounts side by side, for example one for each Google Cloud project. Each destination picks the account it sends with. An account that a destination still uses cannot be deleted: pick another account in that destination, or remove the destination, first.

How the key is stored

GTM4WP encrypts the private key from the file (AES-256-GCM) before storing it. By default the encryption key is derived from the AUTH_KEY, SECURE_AUTH_KEY, AUTH_SALT and SECURE_AUTH_SALT constants in wp-config.php. When you define GTM4WP_ENCRYPTION_KEY there, as described below, it is derived from that constant instead. The private key is never shown again, never sent to the browser and never included in a settings export, so keep your own copy of the file.

The encryption protects the key from someone who can read your database but not your files, for example through a leaked database backup. It only helps while the four constants, or GTM4WP_ENCRYPTION_KEY, are defined in wp-config.php. If they are missing there, WordPress generates the values and keeps them in the database, right next to the encrypted key. Someone who can read both your files and your database can decrypt the key. No plugin can prevent that, which is one more reason to give the account access to a single Analytics property.

Keeping the keys readable when security plugins change the salts

Defining GTM4WP_ENCRYPTION_KEY in wp-config.php keeps the stored service account keys readable when a security plugin replaces the WordPress security keys (salts). Some of these plugins do that on a schedule, and without this constant every replacement makes the stored keys unreadable. Add a secret of your own to wp-config.php:

define( 'GTM4WP_ENCRYPTION_KEY', 'paste a random text of at least 32 characters here' );

The value has to be a text of at least 32 characters. It is not one of the WordPress security keys, so plugins that replace those leave it alone. A value that is too short is ignored: the keys stay encrypted with the WordPress security keys, and an admin notice names the constant until you fix it.

Keys that are already stored move to the new secret automatically, the next time an administrator opens a page in wp-admin or a stored key is used.

Keep the constant once it is defined. Removing it or changing its value makes the stored keys unreadable again. The admin notice then says which of the two happened, and restoring the previous value brings the keys back.

Replacing or rotating the key of an account

To rotate the key of a service account, or to fix a key that can no longer be decrypted, press Replace key next to the account and choose a new key file of the same service account. Create the new key in Google Cloud as described under creating the service account. The account keeps its place in every destination that uses it, so nothing else has to change. A key file of a different service account is refused; add that one as a new account instead. After the replacement the status reads “Not tested yet” until you press Test.

When a stored key can no longer be decrypted

A stored key becomes unreadable when the secret that encrypted it changes. That happens when any of the four WordPress security key constants changes while GTM4WP_ENCRYPTION_KEY is not defined, whether a security plugin replaces them on a schedule or after an incident, and when GTM4WP_ENCRYPTION_KEY itself is removed or changed. GTM4WP then shows an admin notice that names the accounts and the likely cause, their status reads “Key unreadable, use Replace key”, and the Site Health test “Google service account keys are readable” fails. Every Data Manager destination that uses such an account stops sending, and the account list of the destinations marks the account as unreadable.

If the notice says GTM4WP_ENCRYPTION_KEY was removed or changed, restore its previous value in wp-config.php. Nothing else is needed.
Otherwise press Replace key next to the account and choose its key file. If you no longer have it, create a new key for the same service account in Google Cloud.
Press Test to check that the account reaches Google again.

Failed refunds can then be sent again from the Recent sends list of the Google Data Manager section.

Removing an account

Deleting an account in GTM4WP removes the stored key from your site. Uninstalling GTM4WP removes all stored accounts. The key itself stays valid in Google Cloud until you delete it there, under the Keys tab of the service account on the Service Accounts page, so delete it there as well when you no longer use it.