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](https://developers.google.com/google-ads/api/docs/oauth/access-model).

## 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](https://developers.google.com/identity/protocols/OAuth2#serviceaccount) 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](https://developers.google.com/google-ads/api/docs/oauth/service-accounts) 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`](https://github.com/googleads/google-ads-php/blob/HEAD/examples/Authentication/GenerateUserCredentials.php) 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](https://developers.google.com/google-ads/api/docs/oauth/single-user-authentication) 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](https://developers.google.com/google-ads/api/docs/oauth/multi-user-authentication) to learn more.

## Application Default Credentials

The PHP client library also supports authenticating with
[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). 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`](https://github.com/googleads/google-ads-php/blob/HEAD/examples/AccountManagement/GetAccountHierarchy.php) code example shows how to retrieve the list of all accounts under a Google Ads manager account.
2. The [`ListAccessibleCustomers`](https://github.com/googleads/google-ads-php/blob/HEAD/examples/AccountManagement/ListAccessibleCustomers.php) 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.