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:

  https://www.googleapis.com/auth/dfp

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.

Troubleshooting

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.

 - Chris Seeley, DFP API Team

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.

 - Nicholas Chen, DFP API Team