Authentication

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 application 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, understand how the Google Ads access model works. Refer to 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 PHP library can be configured as follows:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withJsonKeyFilePath('INSERT_PATH_TO_JSON_KEY_FILE_HERE')
    // Optional in v32.1.0 and later (defaults to
    // 'https://www.googleapis.com/auth/adwords').
    ->withScopes('https://www.googleapis.com/auth/adwords')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

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 access to a Google Ads API manager account, and link all the Google Ads accounts under that manager account.
2. That user then runs a command-line tool such as GenerateUserCredentials 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:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

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

Multi-user authentication flow

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

// Construct credentials dynamically per authenticated user session.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken($userRefreshToken)
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId($userLoginCustomerId)
    ->build();

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

Application Default Credentials

The PHP client library also supports authenticating with Application Default Credentials (ADC). When neither Application mode (clientId, clientSecret, refreshToken) nor Service account mode (jsonKeyFilePath) credentials are set on OAuth2TokenBuilder, calling build() automatically falls back to Application Default Credentials:

$oAuth2Credential = (new OAuth2TokenBuilder())->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

Manage 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 PHP client library provides the following code examples that illustrate 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.