> [!NOTE]
> **Note:** This guide assumes that you are familiar with the Google Ads access model. If you aren't, we recommend reading the [Google Ads access
> model](https://developers.google.com/google-ads/api/docs/oauth/access-model) guide to familiarize yourself with the concepts. You should also configure your OAuth credentials using the same Google Cloud project where you have [enabled the
> Google Ads API](https://developers.google.com/google-ads/api/docs/oauth/cloud-project#enable-api) and requested an appropriate [API access level](https://developers.google.com/google-ads/api/docs/api-policy/access-levels) for the Google Ads API to work correctly.

> [!CAUTION]
> **Caution:** Google recommends using the [service account
> workflow](https://developers.google.com/google-ads/api/docs/oauth/service-accounts) over the single-user authentication workflow. Use the single-user authentication workflow only when service accounts cannot be used.

Similar to the [service account workflow](https://developers.google.com/google-ads/api/docs/oauth/service-accounts), the
single-user authentication flow makes use of the authorization and user
management features offered by the Google Ads UI to grant the app access to all the
necessary accounts. This authentication workflow has two steps:

- You grant a single user access to **all the Google Ads accounts** that should be managed by the app.
- The user authorizes your app to manage their Google Ads accounts on their behalf, thus granting the app access to all the Google Ads accounts.

Since there is only one user involved, you can rely on tools such as the [gcloud
CLI](https://cloud.google.com/sdk/gcloud/) or the [GenerateUserCredential code
example](https://developers.google.com/google-ads/api/samples/generate-user-credentials) instead of building your own
OAuth 2.0 user authentication flow.

A related use case for this workflow is when your accounts can be accessed
through a handful of user logins (for example, 3 to 4 users), so the development
effort to build a full-blown [OAuth multi-user authentication
workflow](https://developers.google.com/google-ads/api/docs/oauth/multi-user-authentication) isn't justified when compared
to the effort for obtaining authorization for 3 to 4 users using a command-line
tool such as the gcloud CLI.

## Drawbacks

There are a few disadvantages to this flow when compared to the service account
workflow:

- The user authentication workflow requires you to create an OAuth 2.0 client ID and secret in the Google API Console, which requires more configuration steps than creating a service account and key.
- If the authorized user leaves the team or company, then your app may stop working if you remove the user from your accounts or disable the user account. Service accounts are not tied to individual users, so this risk is avoided.
- To protect against account compromise from malware or phishing, the user authorizing the Google Ads account must [authenticate with a
  passkey](https://developers.google.com/google-ads/api/docs/oauth/security-requirements#passkey-requirements) when generating OAuth 2.0 refresh tokens. Service accounts don't require passkeys and are less vulnerable to user-targeted attacks such as phishing.

## Generate credentials

> [!NOTE]
> **Note:** This guide uses a **Desktop app** as the OAuth app type while creating the OAuth credentials, since this works best with the gcloud CLI. When using the single-user authentication workflow, this OAuth app type can be used regardless of the kind of application that you are building. If you choose **Web
> application** instead, you need to use the [OAuth 2.0
> Playground](https://developers.google.com/oauthplayground) to generate a refresh token.

1. [Configure an OAuth consent screen](https://developers.google.com/workspace/guides/configure-oauth-consent) for your
   application and add `https://www.googleapis.com/auth/adwords` as an OAuth
   2.0 scope. See [Setting up your OAuth consent screen](https://support.google.com/cloud/answer/10311615)
   for details.

2. Create a client ID and client secret by following the
   [instructions](https://developers.google.com/workspace/guides/create-credentials#oauth-client-id). Once you create the OAuth 2.0 client,
   download the client's JSON file by clicking the **Download JSON** button on
   the confirmation dialog. Save the file as `credentials.json`.

3. Identify a user account that has access to all the Google Ads accounts you want
   to manage using your app. If there are accounts with missing access,
   [grant account access](https://support.google.com/google-ads/answer/6372672) to that user. Make sure that this user
   account has [set up a
   passkey](https://developers.google.com/google-ads/api/docs/oauth/security-requirements#set-up-passkey) (a 7-day
   security delay may apply before a newly created passkey becomes trusted).

4. [Download and install](https://cloud.google.com/sdk/docs/install) the gcloud CLI. Once installed,
   verify that the tool works correctly by running the `gcloud version` command
   from a command-line prompt. The output looks similar to the following:

       gcloud version

       Google Cloud SDK 492.0.0
       alpha 2024.09.06
       beta 2024.09.06
       bq 2.1.8
       bundled-python3-unix 3.11.9
       core 2024.09.06
       enterprise-certificate-proxy 0.3.2
       gcloud-crc32c 1.0.0

5. Generate an OAuth 2.0 refresh token by running the gcloud CLI tool with the
   `credentials.json` file from the previous step. Passing the
   `--client-id-file` parameter is required so the refresh token is issued
   under your Google API Console project rather than the gcloud CLI's default
   project:

       gcloud auth application-default login \
         --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
         --client-id-file=PATH_TO_CREDENTIALS_JSON

6. The `gcloud` command opens a Google Account sign-in window in a new browser
   window and takes you through the OAuth 2.0 authentication steps. Sign in as
   the user you selected in the previous steps and verify your identity using a
   [passkey](https://developers.google.com/google-ads/api/docs/oauth/security-requirements#passkey-requirements). If your
   app is [unverified](https://support.google.com/cloud/answer/9110914), you might see a warning screen. In such
   cases, it's safe to click the **Advanced** link and click the **Go to
   <var translate="no">PROJECT_NAME</var> (unsafe)** option.


7. After you verify the scopes, click the **Continue** button to grant
   permission. The browser navigates to
   `https://cloud.google.com/sdk/auth_success`, indicating that the
   authentication was successful. The page displays the following message:

   `Authorization code granted. Close this tab.`

   The `gcloud` command prints the following message:

       Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]

   Open the `application_default_credentials.json` file. Its contents are
   similar to the following:

       {
         "account": "",
         "client_id": "******.apps.googleusercontent.com",
         "client_secret": "******",
         "refresh_token": "******",
         "type": "authorized_user",
         "universe_domain": "googleapis.com"
       }

## Client library configuration

Select the tab corresponding to your programming language for instructions on
how to configure your client library. If your authorized user accesses client
accounts through a Google Ads manager account, set `login-customer-id` (or
`loginCustomerId`) to the 10-digit customer ID of that manager account without
hyphens.

### Java

Configure the following keys in your `ads.properties` file.

    api.googleads.clientId=INSERT_OAUTH2_CLIENT_ID_HERE
    api.googleads.clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
    api.googleads.refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
    api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

See the [configuration guide](https://developers.google.com/google-ads/api/docs/client-libs/java/config-file) for additional options.

### .NET

Set the OAuth 2.0 credentials on the `GoogleAdsConfig` instance and use it
to initialize the `GoogleAdsClient` object.

    GoogleAdsConfig config = new GoogleAdsConfig()
    {
        OAuth2Mode = OAuth2Flow.APPLICATION,
        OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE",
        OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE",
        OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE",
        LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
    };
    GoogleAdsClient client = new GoogleAdsClient(config);

See the [configuration guide](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/configuration) for additional options.

### Python

Configure the following keys in your `google-ads.yaml` file.

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
    client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
    refresh_token: INSERT_OAUTH2_REFRESH_TOKEN_HERE
    login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
    use_proto_plus: True

See the [configuration guide](https://developers.google.com/google-ads/api/docs/client-libs/python/configuration) for additional options.

### PHP

Configure the following keys in your `google_ads_php.ini` file.

    [GOOGLE_ADS]
    loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

    [OAUTH2]
    clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
    clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
    refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

See the [configuration guide](https://developers.google.com/google-ads/api/docs/client-libs/php/configuration) for additional options.

### Ruby

Configure the following keys in your
[`google_ads_config.rb`](https://github.com/googleads/google-ads-ruby/blob/HEAD/google_ads_config.rb) file.

    Google::Ads::GoogleAds::Config.new do |c|
      c.client_id = 'INSERT_OAUTH2_CLIENT_ID_HERE'
      c.client_secret = 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
      c.refresh_token = 'INSERT_OAUTH2_REFRESH_TOKEN_HERE'
      c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
    end

See the [configuration guide](https://developers.google.com/google-ads/api/docs/client-libs/ruby/configuration) for additional options.

### Perl

Configure the following keys in your `googleads.properties` file.

    clientId=INSERT_OAUTH2_CLIENT_ID_HERE
    clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
    refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
    loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

See the [configuration guide](https://developers.google.com/google-ads/api/docs/client-libs/perl/configuration) for additional options.

### curl

Start by using an HTTP client to fetch an OAuth 2.0 access token. This guide
uses the `curl` command.

    curl \
      --data "grant_type=refresh_token" \
      --data "client_id=CLIENT_ID" \
      --data "client_secret=CLIENT_SECRET" \
      --data "refresh_token=REFRESH_TOKEN" \
      https://oauth2.googleapis.com/token

You can use the access token in your API calls. The following example
shows how to run a campaign report using the
[`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/SearchStream) method to retrieve the
campaigns in your account. This guide doesn't cover the details of
[reporting](https://developers.google.com/google-ads/api/docs/reporting/overview).

    curl -i -X POST \
      https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds:searchStream \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "login-customer-id: LOGIN_CUSTOMER_ID" \
      --data-binary "@query.json"

The contents of `query.json` are as follows:

    {
      "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
    }