Tag Archives: oauth2

How to properly refresh your OAuth2 access token in DFP API

In July we announced that starting in August 2016, all versions of the DFP API would return HTTP 401 errors instead of SOAP AUTHENTICATION_FAILED errors. We have learned that some developers have been relying on catching an AUTHENTICATION_FAILED error to know when to refresh an access token. This is not the recommended way to determine when your access token needs refreshing and is not supported.

The change described above will break code that relies on catching an AUTHENTICATION_FAILED error. We have temporarily rolled back the change to give developers who haven’t migrated more time to update their code and will roll this change out again on November 30, 2016 and ask that you update your code before then.

Note: If you’re taking advantage of our client libraries, no change is required; our client libraries handle refreshing an access token with our recommended approach.

Instead of relying on an AUTHENTICATION_FAILED error, the recommended way is to calculate how soon the access token is going to expire before making an API call, and refresh it if it’s about to expire soon.

  • Whenever you obtain a new access token, calculate the token’s expiration time by adding the expires_in time returned with the access token to the current time.
    • For example, if you received an access token on Oct 21, 16:05 EDT and the access token lasts for 3600 seconds, the token would expire on Oct 21, 17:05 EDT.
  • Then, before every DFP API call, check when the access token will expire before using it: if it is going to expire within a certain time window (say, in the next 60 seconds), you should refresh it before making the API call.
    • To calculate this, subtract the current time from the token’s expiration time that you calculated above.
You can see an example of how this is done in our Java client library and use it as a reference to help you implement the above.

As always, if you have any questions, feel free to drop us a line on the DFP API forums or the Ads Developer Google+ page.

Demystifying OAuth2 in DFP

Authentication with the DFP API is probably something you had to set up once and then never thought about again. Well, that may be true until there's a scope change, or your credentials suddenly stop working, or the developer who created the credentials leaves to open their own yoga studio in the Andes.

Understanding some of the finer details of DFP's OAuth2 flows can come in handy when the unexpected happens.

Access tokens

When using the DFP API, you can authenticate on behalf of a user in your network or as an application. For the DFP API we call these two choices Web Application flow and Service account flow (server-to-server), respectively. Each choice has a different set-up, but both are used to generate access tokens.

All DFP API requests are authenticated using access tokens. You can think of these as short-lived (about one hour) passwords. When making a request, you include the access token in the HTTP header:

Authorization: Bearer ACCESS_TOKEN

Every access token is tied to a specific user and one or more API scopes. The scopes control which Google APIs the access token is valid for. The scope for DFP is:


Access Control

Because every access token is associated with a user, the DFP API enforces the same exact access controls as the DFP UI. This means that all the teams, roles, and permissions that restrict the user are in effect.

When authenticating as a dedicated API user like a service account, make sure that user is configured with your desired teams and role in DFP. There's no requirement that API users have administrator access.


If you ever need to verify the scope or who the access token was issued to, you can easily do so using the OAuth2 API explorer. Enter the access token you're using, and the API will provide a JSON response with the details:

POST https://www.googleapis.com/oauth2/v2/tokeninfo?access_token=MY_ACCESS_TOKEN
"issued_to": "1234567890-aabbccddgh123.apps.googleusercontent.com",
"audience": "1234567890-aabbccddgh123.apps.googleusercontent.com",
"scope": "https://www.googleapis.com/auth/dfp",
"expires_in": 3496,
"access_type": "offline"

Refresh Tokens

Although we now recommend using service accounts for server-to-server flow, many integrations still use an installed application flow. This flow uses a refresh token to generate access tokens.

If your refresh token stops working, there are a few possible causes:

  • The user you're authenticating as no longer has access to the DFP network.
  • Too many refresh tokens were generated for the OAuth2 client.
  • The user you're authenticating as has revoked access for your application.

The simplest solution to all of these is to create a new client and generate a new refresh token for a current DFP user. Remember that the refresh token is tied to the account that authorizes the application, and not the user who created the OAuth2 client. When accepting the OAuth2 authorization prompt, verify that the user in the top right corner that is logged in is correct:

If OAuth2 still gives you a headache, we're happy to troubleshoot with you. Just reach out to us on our developer forum.

How and when to use service accounts with the Content API for Shopping

The Content API for Shopping documentation now includes a guide for using OAuth 2.0 service accounts with Content API for Shopping. This guide will be of particular interest to in-house developers, whose applications do not need access to third-party information. In such cases, requiring the application to get user approval and to keep track of refresh tokens may be unnecessary overhead. Instead, service accounts provide a private key that the application can use to authenticate when using the Content API.

For developers that work with third-party information, you should still use the OAuth2 three-legged authentication flow as described in the Authorize Requests guide to request permission from users for access to their information.

If you have questions about which flow is more appropriate for your project, or any other questions or feedback concerning the Content API for Shopping, please let us know on the forum.

Changes to DFP API authentication errors

In the past, we’ve thrown AUTHENTICATION_FAILED errors as API exceptions whenever an OAuth2 access token was invalid, expired, or missing. Starting on the release date of v201608, the DFP API will reject these requests as HTTP 401 errors (unauthorized access) instead of as API exceptions for all versions.

If you really break it down, this is a win-win for everyone involved. You don’t waste application quota on authentication requests that are already going to fail, and we can focus on doing what we do best, responding to valid API requests.

What does this mean for you? That’s a bit trickier. If you’re catching the old authentication errors raised by our client libraries, then you’re going to want to shift your integration to catching HTTP errors instead. Since our client libraries are implemented with language-specific practices in mind, you’d be looking for these new occurrences to show up as either errors raised by the underlying HTTP or SOAP libraries or wrapped HTTP errors in the libraries themselves. These failures are generally deterministic and require user action - either to generate a new refresh token, to add a new API user, or to create a valid client - so this is mostly a shift in where to catch the exception rather than wrapping with retry logic.

As usual, if you have any questions or just want to talk about API things, let us know on the developer forum.

OAuth2 Scope Sunset for DFP API

The old DFP API OAuth2 scope has been deprecated. Any API requests using this scope after December 31, 2016 will fail authentication. OAuth2 requests must use the current DFP API scope (https://www.googleapis.com/auth/dfp) after that time.

How can I tell if this impacts me?

If you generated your OAuth2 refresh token after the release of v201408, no action is required. If you're a long-time API user who hasn't updated their refresh token in the last year, you need to generate a refresh token using the current DFP API scope.

If you use a service account to authenticate instead of a refresh token, verify that the scope you use to create credentials is: https://www.googleapis.com/auth/dfp.

If you're still unsure if this affects you, you can follow the steps below anyway with no negative impact.

What action do I need to take?

You have two options to ensure uninterrupted API use:
  1. Use a service account for authentication and set the current DFP API scope. Service accounts simplify the OAuth2 flow by using a public/private key pair instead of a refresh token.
  2. Use the utility provided by your client library to generate a new refresh token using your current client ID and secret. These utilities will use the current scope: After running the utility, update your credentials with the newly generated refresh token.

If you're using a different OAuth2 authentication flow, consult the documentation for your scenario and identify where the scope is being set. If you need clarification, reach out on our developer forum for additional assistance.

Why is this happening?

The OAuth2 scope for DFP was changed in v201408 to better align with the naming conventions of other Google APIs. All versions of the API that were released with the old scope have now been sunset, so the scope is now being sunset. If you have any questions, don't hesitate to post on our DFP API forum.

Sunset of v1 and v1.1 for DoubleClick Ad Exchange Buyer REST API on December 1st, 2014

Today we’re announcing the deprecation of v1 and v1.1 of the DoubleClick Ad Exchange Buyer REST API, both of which are scheduled to be sunset on December 1st, 2014. These versions are becoming increasingly less relevant as we expand on the latest and greatest version of the API—currently v1.3. We recommend that you migrate to v1.3 before this date in order to take advantage of the newest functionality and also to continue having uninterrupted access to the API. If you have not migrated from these deprecated versions by December 1st, calls against the API will return an error response.

The vast majority of users have already migrated to newer versions of the API, but if you’re among the few who haven’t, we expect it to be an easy upgrade because newer versions still support all of the resources you’re familiar with. The only changes that could cause a code break when migrating from v1 to v1.3 are in the Creatives resource; the adgroup_id field was removed and the disapprovalReasons field is no longer a list of strings. You can use the following resources to help you with your migration:
  • Release Notes: A listing of all changes between versions of the API.
  • Code Examples: Examples demonstrating how to use the client libraries with the most recent version of the API.
  • Developer Guides: Guides covering the most recent version of the API.
Of course, if you have any questions or need help with the migration, feel free to reach out to us via the forum or the Ads Developers G+ page.

Announcing OAuth 2.0 service account support for the DFP API

Until now, the DFP API only supported the OAuth 2.0 native/installed application flow. The OAuth 2.0 service account flow was only supported it you had a Google Apps for Business Account. Today, we’re unveiling the new OAuth 2.0 service account flow for DFP. This authorization flow has been simplified to no longer require a Google Apps domain. We’ve also updated the DFP web UI to allow service accounts to be added to be a DFP network.

Why should I use service accounts?

Service accounts allow access to Google APIs without the need for user interaction by authenticating solely with server-to-server interactions. Other OAuth 2.0 flows require user interaction or having an application cache a refresh token.

How do I use service accounts?

  1. Generate a service account key from the Google Developers Console.
  2. Add the service account to your DFP network by going to the Admin tab and clicking the Add a service account user button.
  3. Fill in the form with your Name, Email, Teams (if applicable), and Role. Then, click Save.
  4. View existing service account users by going to the Users tab and then clicking the Service Account filter.

With the *.p12 key generated from the Google Developers Console and the service account added to the DFP network, you can now generate an OAuth 2.0 token. For example, using the Java client library:

    GoogleCredential credential = new GoogleCredential.Builder().setTransport(
new NetHttpTransport())
.setJsonFactory(new GsonFactory())
.setServiceAccountPrivateKeyFromP12File(new File("/path/to/key.p12"))

For more information, see our updated guide on using service accounts with DFP.

New OAuth 2.0 Scope for the AdWords API

A new OAuth 2.0 scope for the AdWords API was introduced along with the v201406 client library release. The OAuth 2.0 scope identifies the service that your application can access during the authorization process.

The new scope is: https://www.googleapis.com/auth/adwords. This new scope better aligns with the naming conventions of many of the other Google APIs.

Starting today, use the new scope when authorizing access for the AdWords API regardless of the AdWords API version. All our current AdWords API client libraries use this new scope.

But I have refresh tokens from the deprecated scope...

Don’t worry if your client code is using refresh tokens authorized with the deprecated scope - they will still work. However, new authorizations should specify the new scope.

As always, if you have any questions, drop us a line on the AdWords API forum or Ads Developers Google+ page.

AdWords and DoubleClick Ad Exchange API users – Only 3 weeks left to migrate from ClientLogin to OAuth 2.0!

ClientLogin authentication support for the AdWords API and the DoubleClick Ad Exchange API will sunset along with v201309 on July 21st, 2014. You only have 3 weeks left to migrate!

We have plenty of resources to help you migrate. It might take longer than you expect to migrate to OAuth 2.0, especially if you don't already use a single top-level MCC to manage your AdWords accounts or if you are a DoubleClick Ad Exchange customer.

Start your migration as soon as possible and reach out to us early on the AdWords API Forum or the DoubleClick Ad Exchange API Forum with any questions.

Updated DoubleClick Ad Exchange Buyer REST API examples to get you started

Whether you’re just starting out with the DoubleClick Ad Exchange Buyer REST API or are working with an unfamiliar client library, our examples will help you get started! Our examples are now on GitHub and have been expanded to cover the following languages:

Each of these include documentation to help you get started with the corresponding client library and demonstrate how you can use the Service Account authorization flow with the DoubleClick Ad Exchange Buyer REST API.

If you have any feedback or feature requests for these examples, we’d definitely be interested in hearing about it! Feel free to contact us via the forum or our Google+ page.