Authentication and Authorization

Like other Google APIs, the Google Ads API uses the OAuth 2.0 protocol for authentication and authorization. OAuth 2.0 enables your Google Ads API client app to access a user's Google Ads account without having to handle or store the user's login info.

Understand the Google Ads Access Model

To work effectively with the Google Ads API, you should understand how the Google Ads access model works. We strongly recommend reading the Google Ads access model guide.

OAuth workflows

There are three common workflows used when working with the Google Ads API.

Service account flow

This is the recommended workflow if your workflow doesn't require any human interaction. This workflow requires a configuration step, where the user adds a service account to their Google Ads account. The app can then use the service account's credentials to manage the user's Google Ads account. The library is configured as follows:

// Initialize a GoogleAdsConfig class.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = ******
};

// Initialize a GoogleAdsClient class.
GoogleAdsClient client = new GoogleAdsClient(config);

Refer to the service account workflow guide to learn more.

Single-user authentication flow

This workflow may be used if you cannot use service accounts. This workflow requires two configuration steps:

1. Give a single user access to all the accounts to be managed using the Google Ads API. A common approach is to give the user to a Google Ads API manager account, and link all the Google Ads accounts under that manager account.
2. The user runs a tool such as gcloud CLI or the GenerateUserCredentials code example to authorize your app to manage all their Google Ads accounts on their behalf.

The library can be initialized using the user's OAuth 2.0 credentials as follows:

GoogleAdsConfig googleAdsConfig = new GoogleAdsConfig()
{
    DeveloperToken = DEVELOPER_TOKEN,
    LoginCustomerId = LOGIN_CUSTOMER_ID,
    OAuth2ClientId = OAUTH_CLIENT_ID,
    OAuth2ClientSecret = OAUTH_CLIENT_SECRET,
    OAuth2RefreshToken = REFRESH_TOKEN,
};

GoogleAdsClient googleAdsClient = new GoogleAdsClient(googleAdsConfig);

Refer to the single-user authentication workflow guide to learn more.

Multi-user authentication flow

This is the recommended workflow if your app allows users to sign in and authorize your app to manage their Google Ads accounts on their behalf. Your app builds and manages the OAuth 2.0 user credentials. The library can be initialized using the user's credentials as follows:

GoogleAdsConfig googleAdsConfig = new GoogleAdsConfig()
{
    DeveloperToken = DEVELOPER_TOKEN,
    LoginCustomerId = LOGIN_CUSTOMER_ID,
    OAuth2ClientId = OAUTH_CLIENT_ID,
    OAuth2ClientSecret = OAUTH_CLIENT_SECRET,
    OAuth2RefreshToken = REFRESH_TOKEN,
};

GoogleAdsClient googleAdsClient = new GoogleAdsClient(googleAdsConfig);

Refer to the multi-user authentication workflow guide to learn more. The .NET client library includes two code examples for reference:

1. The AuthenticateInAspNetCoreApplication code example illustrates how to build a web app that obtains user authentication at runtime to manage their Google Ads accounts on their behalf. The app uses the user's OAuth 2.0 credentials to retrieve the campaigns in their Google Ads account.

2. The GenerateUserCredentials is a command line code example that illustrates how to obtain user authentication at runtime to manage their Google Ads accounts on their behalf. You can use this code example as a reference to build desktop apps that require user authentication.

What if my user manages multiple accounts?

It is common for a user to manage more than one Google Ads account, either through direct access to accounts, or through a Google Ads manager account. The .NET client library provides the following code examples that illustrates how to handle such cases.

1. The GetAccountHierarchy code example shows how to retrieve the list of all accounts under a Google Ads manager account.
2. The ListAccessibleCustomers code example shows how to retrieve the list of all accounts that a user has direct access to. These accounts can then be used as valid values for the LoginCustomerId setting.