All AdWords API calls must be authorized through OAuth2. OAuth2 enables your AdWords API client app to access a user's Google Ads account without having to handle or store the user's login info.
Generate OAuth2 credentials
Perform the following steps to generate OAuth2 credentials.
Determine your app type
First, determine the appropriate app type for the app you want to build. There are two app type options for the AdWords API:
- Installed application (recommended)
- Web application
Check the table below to see which type is most appropriate for the app you want to build:
Choose this app type | If ... |
---|---|
Installed app (recommended) |
|
Web app |
|
For more details see the Google Identity Platform OAuth documentation for installed apps and web apps.
Create a client ID and client secret
Once you've determined your app type, click the corresponding tab below and follow the instructions to generate the OAuth2 client ID and client secret:
- Open the Google API Console Credentials page.
- Click Select a project, then NEW PROJECT, and enter a name for the project, and optionally, edit the provided project ID. Click Create.
- On the Credentials page, select Create credentials, then OAuth client ID.
- You may be prompted to set a product name on the Consent screen; if so, click Configure consent screen, supply the requested information, and click Save to return to the Credentials screen.
- Select Desktop app for the Application type, and enter any additional information required.
- Click Create.
- On the page that appears, copy the client ID and client secret to your clipboard, as you will need them when you configure your client library.

- Open the Google API Console Credentials page.
- Click Select a project, then NEW PROJECT, and enter a name for the project, and optionally, edit the provided project ID. Click Create.
- On the Credentials page, select Create credentials, then OAuth client ID.
- You may be prompted to set a product name on the Consent screen; if so, click Configure consent screen, supply the requested information, and click Save to return to the Credentials screen.
- Select Web Application for the Application Type. Follow the instructions to enter JavaScript origins, redirect URIs, or both.
- Click Create.
- On the page that appears, copy the client ID and client secret to your clipboard, as you will need them when you configure your client library.

Configure and use a client library
Follow the appropriate guide below to use the OAuth2 credentials in the configuration for your language's client library:
Java
.NET
Python
PHP
Perl
Ruby
OAuth2 Playground
Another option for generating OAuth2 credentials is to use the OAuth2 Playground. The OAuth2 Playground, in conjunction with the Google API Console, allows you to manually create OAuth2 tokens.
The OAuth2 Playground is for users who only need to access the accounts for a single manager account or Google Ads user. If you need to prompt multiple users for credentials, then the client library-based approach described above is likely better.
Setup
Get a client ID and client secret
Open the Google API Console Credentials page.
From the project drop-down, select an existing project or create a new one.
On the Credentials page, select Create credentials, then select OAuth client ID.
Under Application type, choose Web application.
Under Authorized redirect URIs, add a line with:
https://developers.google.com/oauthplayground
Click Create.
On the page that appears, take note of the client ID and client secret. You'll need these in the next step.
Generate tokens
Go to the OAuth2 Playground via this link, which should pre-populate some key values for you.
Click the gear icon
in the upper right corner and check the box labeled Use your own OAuth credentials (if it isn't already checked).
Make sure that:
- OAuth flow is set to Server-side.
- Access type is set to Offline (this ensures you get a refresh token and an access token, instead of just an access token).
Enter the OAuth2 client ID and OAuth2 client secret you obtained above.
In the section labeled Step 1 - Select & authorize APIs, enter the following URL in the text box at the bottom, if it's not already there, then click Authorize APIs:
https://www.googleapis.com/auth/adwords
If prompted, log in to the account to which you want to grant access and authorization. Otherwise, confirm that the current Google user in the top right corner is the Google Ads or manager account for whom you want to obtain credentials.
A prompt appears indicating your app would like to Manage your Google Ads Campaigns. Click Accept to continue.
In the tab labeled Step 2 - Exchange authorization code for tokens, you should now see an Authorization code. Click Exchange authorization code for tokens.
If all goes well, you should see the Refresh token and Access token filled in for you (you may have to re-expand Step 2 - Exchange authorization code for tokens to see these values):
Copy the Refresh token into the configuration file for your client library of choice, along with the client ID and client secret. See the instructions above to set configuration options for your client library of choice.
Remove the OAuth2 Playground from your client ID
Now that you have a refresh token, you no longer need the OAuth2 Playground to be an authorized redirect URI. To remove it from the list of authorized redirect URIs:
Go to the Google API Console Credentials page.
From the project drop-down, select your project.
On the Credentials page, click the client ID name to edit.
Remove
https://developers.google.com/oauthplayground
from the Authorized redirect URIs. Note that you must leave at least one redirect URI in place.Click Save.
You now have the OAuth credentials you need to issue AdWords API requests, and to try out the code samples for your client library of choice.
OAuth2 service accounts
This section discusses how to access the AdWords API with service accounts.
A service account is an account that belongs to your application instead of to an individual end user. Service accounts allow server-to-server interactions between a web application and a Google service. Your application calls Google APIs on behalf of the service account, so users aren't directly involved.
The AdWords API allows service account access through G Suite domains.
Service accounts employ an OAuth2 flow that doesn't require human authorization, but uses instead a key file that only your app can access.
Using service accounts provides two key benefits:
- Authorization for an app to access a Google API is done as a configuration step, avoiding the complications associated with other OAuth2 flows that require user intervention, or that require your app to cache tokens to avoid user intervention.
- OAuth2 assertion flow allows your app to impersonate other users if necessary.
An alternative to service accounts
Developers often consider using service accounts because they want programmatic access to the API using OAuth2 without user intervention.
Because of the complexity of setting up service account access for the AdWords API, we recommend a simpler alternative that achieves the same goal, which is to use the OAuth2 installed application flow and persist the refresh token. This way, your app will always be able to request a new access token when necessary.
This process requires you to authorize your app during by configuring your client library according to the installed app procedure outlined above. This only needs to be done once, since Google OAuth2 refresh tokens don't expire.
Prerequisites
- A G Suite domain that you own such as mydomain.com or mybusiness.com.
- An AdWords API developer token and optionally a test account.
- The client library for the language you're using.
Setting up service account access
First you must generate a service account key in the Google API Console:
While logged in to your G Suite account, open the Google API Console.
Click Select a project at the top of the screen, then NEW PROJECT. Supply the requested information and click Create. After a moment, the new project becomes the active project.
From the menu in the upper left corner, choose IAM & admin, then select Service accounts.
Click Create service account at the top.
Enter a name for the service account.
Check Furnish a new private key, and select JSON as the key type.
Click Create. The JSON key file is downloaded to your machine. Store it in a safe place that only you can access.
The new service account is shown on the Service Accounts page for the project.
Security concerns
Because of G Suite's domain-level control, it's important to protect the key file that allows a service account to access the Google services for which it's authorized. This is especially true since that service account will have the ability to impersonate any user in the domain.
Another good practice is to allow service accounts to access only one Google API each (using the scope field described in the following section). This is a preemptive measure to limit the amount of data an attacker can access if the service account's key file is compromised.
Granting impersonation abilities
Perform the following steps to grant impersonation abilities to a service account:
Add a new authorized API client to your G Suite domain by going to:
https://admin.google.com/YOUR_DOMAIN/ManageOauthClients
Add a new authorized API client as the Client Name, using the client ID from the JSON file you generated in the steps above.
Enter the following for the API scope:
https://www.googleapis.com/auth/adwords
Repeat the process for all other service accounts to which you want to grant impersonation power.
You can now use the service account to access your Google Ads account via the OAuth2 assertion flow.
Configuring your client library
Select your language below for instructions to configure your client library.
Java
See the instructions in GitHub to configure the client library for your service account.
.NET
See the instructions in GitHub to configure the client library for your service account.
Python
See the instructions in GitHub to configure the client library for your service account.
PHP
See the instructions in GitHub to configure the client library for your service account.
Perl
See the instructions in GitHub to configure the client library for your service account.
Ruby
See the instructions in GitHub to configure the client library for your service account.
Optimizing OAuth2 requests
If your app doesn't share credentials across servers, processes, and threads, it may be sending an excessive number of requests to Google. This can cause our servers to enforce rate limits on your app, resulting in performance degradation.
This section explains how to optimize OAuth2 credential management so your app can efficiently interact with the AdWords API.
Credential sharing strategies
Sharing credentials across your API requests improves performance and avoids excessive overhead that can result in rate limit errors.
Your credential sharing strategy depends on your app's design:
- Multithreaded apps share a thread-safe credential.
- Multiprocess or distributed apps share a credential via a shared data store.
In multithreaded apps, you should supply each thread's session with the same credential.
In multiprocess or distributed apps, you must implement some infrastructure to share the credential across processes. You should also ensure that threads aren't blocked, and that race conditions aren't present in your implementation.
An app that is both multiprocess / distributed and multithreaded within each process should use both strategies.
These strategies are described below for authenticating a single Google Ads account, such as the top-level manager account in your hierarchy.
Adapting these strategies to authenticate for multiple Google Ads accounts is described after.
Multithreaded apps
In multithreaded apps, the credential should be shared between threads. Refreshing of the credential should be performed synchronously to avoid a race condition.
The diagram shows a runtime with threads drawing from a pool of sessions (or users) to make requests to the AdWords API. Note that each session should use the same credential object. On each API request, the thread obtains a session (or user). If the credential requires an access token refresh, it must be done synchronously—that is, the credential object must be thread-safe—to avoid a race condition.
The client libraries make sharing a credential across threads straightforward. Each client library has a session (or user) object with a credential that it reuses throughout its lifetime. To share the credential across threads, simply construct each session using the same credential. In all client libraries, the credential is a thread-safe object that refreshes itself synchronously when its access token expires.
For example, in the Java client library, you would create a Credential
as a
singleton and share it across all sessions.
Multiprocess or distributed apps
In multiprocess or distributed apps, sharing the credential requires you to persist it. To ensure multiple processes or servers don't attempt to refresh the credential at the same time (resulting in excessive refresh requests), we advise proactively refreshing the credential in a central place and sharing it across processes/servers.
For example, a separate job or service can be responsible for periodically refreshing the credential, and proactively pushing it to the data store for use by the pool of servers.
The diagram shows the credential refresh job running periodically and writing the credential's properties to the data store. Each server then retrieves the credential before making a request to the API.
Refresh job
The refresh job periodically refreshes the credential and stores it in the data store. The job shouldn't wait until the current credential expires before initiating a refresh: Doing so would open a window when the app is stalled for lack of a valid credential.
A better alternative is to force the refresh periodically, each time replacing the credential in the data store with the new one. The refresh job should run well before the current credential expires to allow some time in case of a transient failure. Every 15 minutes is a good starting point.
Data store
A central data store can be used to share the credential between processes and servers.
You can make use of an existing data store or deploy one specific to the sharing of credentials between servers. Solutions include caching servers (such as Memcached or Infinispan), or NoSQL data stores (such as MongoDB).
The data store must provide a reliable interface to all the servers making requests to the API. It should be optimized for fast reading operations, since the server or process will read the current credential more frequently than the refresh job will update it.
Keep in mind that credentials must be stored securely.
When storing the credential, you should store the calculated expiry_time
(now + expires_in
) and refresh_token
alongside the access_token
. The expiry_time
is calculated as the time of the
access_token
refresh request plus the expires_in
time.
Server pool
Each server or process in the pool retrieves the latest credential from the data store before making a request. As long as the refresh job is running successfully, the credential will be valid. But if the refresh job or data store fails, you should have a fallback mechanism.
If a server or process cannot get a credential from the data store, or if the credential is expired, the server should refresh its own credentials to allow the app to continue working with the API until the problem is resolved.
In processes with multiple threads, you should use the same sharing strategy described above to share the credential across threads.
Authenticating multiple accounts
A credential generated for an Google Ads manager account can be used to access all its child accounts. Thus, for users with a single manager account hierarchy, it's usually sufficient to generate a credential for the top-level manager account, thereby authorizing the app for all the Google Ads accounts beneath it.
In other cases, your app must access Google Ads accounts that are not related to one another in any manager account hierarchy. In this case, you should generate and maintain different credentials for different accounts, such as for each Google Ads client account you access, or each top-level manager account in the independent hierarchies you access.
You can follow the same strategies for multithreaded
and multiprocess / distributed
apps with minor modification. When using a shared data store,
credentials must be indexed by the account identifier customerId
to
ensure credentials are associated with the right account.
Additionally, the refresh job should keep all credentials
refreshed. If a new account is linked, the refresh job may need to be triggered.
Finally, in multithreaded apps, you should only share the credential object across threads that are operating on the account with which the credential object is associated.
OAuth2 internals
Our client libraries automatically take care of the details covered below, so read on only if you're interested in what's happening behind the scenes, or if you're not using one of our client libraries.
This section is intended for advanced users who are already familiar with the OAuth 2.0 specification and know how to use OAuth2 with Google APIs.
Scope
A single access token can grant varying degrees of access to multiple APIs. A
variable parameter called scope
controls the set of resources and operations
that an access token permits. During the access token request, your app
sends one or more values in the scope
parameter.
The present and deprecated scopes for the AdWords API:
Scope | Meaning |
---|---|
https://www.googleapis.com/auth/adwords |
Read/write access to AdWords API. |
|
This scope is deprecated and should no longer be used to obtain future authorizations. Previously authorized tokens will continue to work. |
Offline access
It's common for an AdWords API client app to request offline access. For example, your app may want to run batch jobs when your user is not physically online browsing your website.
To request offline access for a web application type, make sure you set the
access_type
parameter to offline
. You can find additional information in
Google's OAuth2
guide.
For installed application type, offline access is enabled by default - you don't have to explicitly request it.
HTTP request header
The HTTP header in every request to the AdWords API server must include the access token in this form:
Authorization: Bearer THE_ACCESS_TOKEN
For example:
POST … HTTP/1.1
Host: …
Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3Zg
Content-Type: text/xml;charset=UTF-8
Content-Length: …
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope">
…
</soap:Envelope>
Access and refresh token
In most cases, you need to store the refresh token securely for future use. To learn more about how to request access and refresh tokens, read the guide corresponding to your application type:
Access token expiration
An access token has an expiration time (based on the
expires_in
value) after
which the token is no longer valid. You can use the refresh token to refresh
an expired access token. By default, our client libraries automatically
refresh expired access tokens.