Authentication in the AdWords API

in AdWords API

This article outlines the mechanisms that can be used to login to a Google account with the AdWords API. I present a higher level overview here that doesn't contain any code, but if you want to get into the code itself, then you can check out my tutorial about using OAuth 2.0 with the AdWords API.

Google's Authentication APIs

When using the AdWords API—or any Google API for that matter—you don't actually send them the username and password for the account you want to access; instead, you use a different API to request an access token, then send this token to the AdWords API to prove your application is permitted to manage an account. Google has several API's for this purpose:

  • The ClientLogin API – A proprietary API that takes a username and password, then generates a token for it.
  • The OAuth API – An open standard that enables a user to log into their account to grant your application access it; your application is sent an access token that can be used instead of a username and password.
  • The AuthSub API – Another proprietary Google API that works in a similar way to OAuth.

The AuthSub API is a legacy system, which has now been deprecated, that was never implemented for the AdWords API, so I won't discuss it any further. Up until October 2011, the only way of authenticating an AdWords API was using ClientLogin, but you can now use OAuth as well; the next section will discuss why you would want to use OAuth in you tools instead on the ClientLogin API, then the following section will outline the versions of OAuth available for use with the AdWords API.

The Benefits of OAuth over the ClientLogin API

While it's fine to use passwords for your own accounts, or the ones you manage, you can loose potential customers when you ask them to enter their password on a sign-up form for an application. The OAuth process removes the need for passwords by using access tokens instead: You ask the user to log into their Google account and give your tool access to selected services, such as AdWords, then you receive a code that can be used to make API calls without being required to present a username or password. There are several other disadvantages of the ClientLogin API that make OAuth preferable.

  • A token is still required, but it expires after two weeks; you can get a new token for every request, but if you ask for too many tokens from the ClientLogin API within a short period of time, you can end up being rejected and presented with a CAPTCHA challenge, which needs to be resolved manually before your application can continue.

  • You need to ensure that you keep your system up to date with the latest passwords; when a user changes their password, current tokens will become invalid, but your software won't be able to request a new token until it knows the new password.

  • Google has recently introduced an additional security measure for their accounts called two-step verification: This means that the ClientLogin API won't be able to grant access based on a password alone, so you need to ask users to go into their account and generate a special password just for your application.

  • OAuth can be used to obtain access to more than one Google API in one step; for example, you can ask a user to let your application access both their AdWords and Google Analytics data in one visit to the Google OAuth page.

  • As of April 2012, the ClientLogin API has been officially deprecated, and will be discontinued in 2015.

Given all of this, the oAuth authentication mechanism is a welcome addition to the AdWords API, and one that you should be keen to leverage.

How OAuth Works

OAuth works by replacing the normal username and password combination that's required for logging into an account with an identification token; you send the user to a page on Google where they sign into their account and authorize your application, then they are redirected back to your website with an access token that you can use to call the AdWords API.

While using the AdWords API with the ClientLogin API also requires an access token, you need to exchange a username and password for it, and thus need to store these for future use when the token expires; however, with OAuth you can obtain a refresh token that can be stored and used to request a new access token when it expires, without needing to store a user's credentials.


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.