Getting AdWords API Tokens from the OAuth Playground

in AdWords API

This article describes a simple way to grab some OAuth 2.0 tokens for use in an AdWords API application. OAuth is great for building tools that access third-party accounts, but is a hurdle when you're just getting started with the AdWords API or when you are just using your own account. Fortunately, Google provides a tool, called the OAuth Playground, that you can use to generate some tokens quickly.

Google's OAuth Playground

The OAuth Playground is a tool for learning how OAuth works. It presents you with a three-step process for selecting the services you want to authorize, generating an access token, and making API requests. However, the access token only lasts for an hour and you can't select the AdWords API at the moment, so you need to perform a few additional steps:

  • Create your own client id and secret so you can generate new access tokens in your own code.
  • Add the client id and secret to the playground.
  • Configure the tool to use the AdWords API.

Generating a Client ID and Secret

You can sign up for a Client ID and Secret from the Google API Console. If you've used it before, the process is similar to generating tokens for the web flow, but you need to set the redirect URL to point back to the OAuth Playground at developers.google.com/oauthplayground instead of your own website.

If you haven't used the console before, you'll see the following screen after logging into your account:

Creating a New API Project
Creating a New API Project

Just press the Create Project button to generate a generic project, called “API Project”, then you will be taken to the dashboard. You create tokens using the API Access tab:

The API Access Tab of a New Project
The API Access Tab of a New Project

Pressing the Create and OAuth 2.0 Client ID… button will bring up a wizard to guide you through the token creation process. If you haven't created any tokens yet, then you'll be asked to enter some branding information first. Just enter a name for your application, and click on the Next button to specify the settings for your application:

The Token Settings Dialog
The Token Settings Dialog

Leave the Web application radio button checked, enter developers.google.com/oauthplayground into the textbox, then press Create client ID. Once this is complete, you'll be shown a screen containing your Client ID and Client Secret:

Your New Client ID and Client Secret
Your New Client ID and Client Secret

Adding the Client ID and Secret to the Playground

Now you need to enter your tokens into the settings dialog of the OAuth Playground:

The OAuth Playground Settings Dialog
The OAuth Playground Settings Dialog

Tick the Use your own OAuth credentials checkbox, then enter your Client ID and Client Secret into the OAuth Client ID and OAuth Client secret textboxes:

Entering Your Tokens into the Playground
Entering Your Tokens into the Playground

Selecting the AdWords API Scope

You can now generate some tokens using your own credentials, but the AdWords API isn't available in the list of APIs options, so you need to enter its scope into the box at the bottom of the list:

Entering the AdWords API Scope into the Playground
Entering the AdWords API Scope into the Playground

Generating Some Tokens for Your Account

Now that you've configured the tool, you can get an access and refresh token. Press the Authorize APIs button, and you will be taken to a dialog to authorize your account:

Authorizing Your Account for the AdWords API
Authorizing Your Account for the AdWords API

Pressing the Accept button will take you back to the OAuth playground with an initial code that you can use to generate full OAuth tokens:

An Initial OAuth Code
An Initial OAuth Code

Generate the full OAuth tokens by pressing the Exchange authorization code for tokens button:

Your OAuth Access and Refresh Tokens
Your OAuth Access and Refresh Tokens

Using the Tokens in Your Scripts

Now that you've got some tokens, you can now plug them into your scripts. Here's an example of pulling a keyword performance report using the PHP client library:

<?php
 
set_include_path(get_include_path() . PATH_SEPARATOR .
        dirname(__FILE__) . "/adwords_api_php_4.5.1/src");
require_once("Google/Api/Ads/AdWords/Lib/AdWordsUser.php");
 
define("OAUTH_CLIENT_ID", "[YOUR CLIENT ID]");
define("OAUTH_CLIENT_SECRET", "[YOUR CLIENT SECRET]");
define("OAUTH_ACCESS_TOKEN", "[YOUR ACCESS TOKEN]");
define("OAUTH_REFRESH_TOKEN", "[YOUR REFRESH TOKEN]");
define("CUSTOMER_ACCOUNT_ID", "[YOUR ACCOUNT ID]");
define("DEVELOPER_TOKEN", "[YOUR DEVELOPER TOKEN]");
define("API_VERSION", "v201306");
 
$user = new AdWordsUser();
$user->SetDeveloperToken(DEVELOPER_TOKEN);
$user->SetClientCustomerId(CUSTOMER_ACCOUNT_ID);
 
$user->SetOAuth2Info(array(
    "client_id" => OAUTH_CLIENT_ID,
    "client_secret" => OAUTH_CLIENT_SECRET,
    "access_token" => OAUTH_ACCESS_TOKEN,
    "refresh_token" => OAUTH_REFRESH_TOKEN
));
 
$user->LoadService('ReportDefinitionService', API_VERSION);
 
$reportFormat = "TSV";
 
$reportQuery = "SELECT Id, KeywordText, KeywordMatchType, Impressions, Clicks " .
        "FROM KEYWORDS_PERFORMANCE_REPORT " .
        "DURING THIS_MONTH ";
 
$options = array(
    'version' => API_VERSION,
    'includeZeroImpressions' => true,
    'returnMoneyInMicros' => true
);
 
$report = ReportUtils::DownloadReportWithAwql($reportQuery, null, $user, $reportFormat, $options);
 
print $report;
?>
Using OAuth Tokens in an AdWords API PHP Script

Once your Access Token has expired, you can refresh it using the following code:

$handler = $user->GetOAuth2Handler();
$oauth2Info = $handler->RefreshAccessToken($user->GetOAuth2Info());
$user->SetOAuth2Info($oauth2Info);
Refreshing an Access Token

If you're running this less than once per hour, you can just call the refresh code each time the script runs.

← Uploading Cost Data into Google Analytics Ad Sitelinks in the AdWords API →

To help me decide what to write about, I'd like to asses the value of my blog posts to see which ones people find most beneficial. If you found the information here useful then could you please +1 it, but if you didn't find what you were looking for then please leave a comment and I'll be happy to help where I can. Thanks!

Comments

I'm keen to get feedback on my posts, so if you have any questions or comments, then please send me a message and I'll be happy to help.