Join us live on Discord on the Google Advertising and Measurement Community server and on YouTube on October 15th at 10:00 AM EST! We will discuss the new features added in v26 of the Google Ads API.

Shared aliases

Page Summary

Multiple email addresses are used for contact and access management when working with the Google Ads API, including the Google Ads API contact email, Google Cloud Console account email, and Google Ads manager account email(s).
Using shared team aliases for these email addresses is strongly recommended to maintain access when individuals leave the company.
The Google Ads API contact email is used for communication from Google regarding API reviews, audits, or emergencies and should be a shared alias monitored regularly.
The Google Cloud Console account email, which has administrator access to the project with OAuth credentials, should be a shared alias to ensure access.
Google Ads manager account emails are used for issuing refresh tokens and accessing accounts via the API, and using a shared alias with appropriate access levels for this purpose prevents loss of access if an individual's access changes.

When working with the Google Ads API, email addresses are used in multiple places for contact and access management. The most important of these are:

Google Ads API contact email: The email addresses assigned the Owner or Editor role on your Google Cloud project, which Google uses to send Mandatory Service Announcements (MSAs) and administrative notifications.
Google Cloud Console account email: The email that holds administrator access to the Google Cloud project used for your OAuth 2.0 application.
Google Ads manager account access: The service account (recommended) or shared email alias that holds access permissions on the Google Ads manager account(s) accessed through the Google Ads API.

The rest of this guide elaborates on each of the accounts listed earlier and how you can configure them so your integration doesn't depend on an individual user's email address.

Google Ads API contact email

Google sends administrative notifications, API review updates, audit requests, Mandatory Service Announcements (MSAs), and production emergency communications to the email addresses associated with the Owner and Editor roles of your Google Cloud project (see New API contact emails, as the legacy API Center contact email setting in the Google Ads UI has been sunset).

To update your contact email and ensure that your whole team receives these notifications, grant the Owner or Editor role to a shared team alias in your Google Cloud project and monitor emails sent to that alias regularly.

Google Cloud Console account

The Google Cloud Console project contains your application's OAuth credentials and controls access to the Google Ads API. Ensure access to this project by granting a shared team alias the Owner (or Editor) role.

Follow these steps to add a shared alias as a Google Cloud project owner:

Sign in to the Google Cloud Console.
Select your project from the project selector at the top of the page.
In the navigation menu, go to IAM & Admin > IAM.
Click Grant Access.
In the Add principals section, enter the shared email address in the New principals field.
In the Assign roles section, click Select a role, and select Basic > Owner (or Basic > Editor).
Click Save. If you granted the Owner role to an email address outside your Google Cloud organization (or on a project without an organization), Google Cloud sends an invitation email to the shared alias that must be accepted before the role takes effect. Refer to the Cloud documentation to learn more about granting and revoking access.

Google Ads manager account

A common method of managing accounts using the Google Ads API is to link all your accounts under a common manager account, and make API calls to all the accounts using the top-most manager account's credentials. In this configuration, the developer sets the login-customer-id request header (or login_customer_id client library configuration setting) to the 10-digit customer ID (without hyphens) of the Google Ads manager account, and sets the target customer_id to the operating account to which API calls are made.

Recommended: Use a service account

Using a service account is the preferred approach for authenticating and accessing a Google Ads manager account. Unlike individual user accounts, a service account is managed within your Google Cloud project and is not tied to a specific person, preventing outages when team members change roles or leave the company. Follow the service account guide to create a service account and grant it access to your Google Ads manager account.

Alternative: Use a shared email alias

If your integration cannot use a service account and instead relies on the single-user authentication workflow, a user with access to the Google Ads manager account issues an OAuth 2.0 refresh token.

To avoid this scenario when using user credentials:

Invite a shared email alias (backed by an active Google Account with passkey verification enabled) to manage this Google Ads manager account with the appropriate access levels.
Accept the invitation using the shared email alias.
Use this shared email alias to issue the OAuth refresh token for making API calls.

Rate limits

Stay updated