Authorization tokens were introduced with v2009 as part of the authorization mechanism adopted for the new version, ClientLogin. This new approach allows us to separate authorization from API requests, making it a two step process: first retrieve a token, and then include it with your requests.
How ClientLogin works
ClientLogin was designed as a standalone authentication and authorization procedure that returns a token, if successful. This token is then supplied together with the requests as a form of proof that the user is who they claim to be, and that they are allowed access to the API. Since both the authorization and the requests happen over SSL connections, there is no risk of anyone retrieving the token and impersonating the user.
Explaining how to implement a full ClientLogin handler is outside the scope of this blog post, but for the full details on the protocol please consult the documentation. Here is a small example of how to log in using the AuthToken module included with the Ruby client library (which can be used outside of it, since its only dependency is the httpclient gem):
require 'authtoken'
auth_token = AdWords::AuthToken.get_token(email, password,
'www.google.com', 443, true)
Other client library projects include NoClientLib pages in their wikis detailing how to perform the ClientLogin step (as well as all other steps in a successful request) without the client library.
If you’re using the client libraries, the ClientLogin step is usually handled for you, although you’ll still need to keep an eye out for any errors. The Readme file included with your client library has more details.
Remember to reuse the authorization tokens
This is a point of some confusion among developers, and illustrates one of the key differences in authorization between v13 and v2009: In v13, you authenticated and authorized every request by sending your account credentials as part of the header; in v2009, you authenticate with ClientLogin beforehand and then authorize your request to the AdWords API by supplying the token generated by ClientLogin.
A naive migration from v13 to v2009 would generate a new token for every request and insert it into the header. This is a bad idea. Such an implementation will very likely cause your software to run into CAPTCHAs and block your accounts until the CAPTCHAs are resolved.
A correct implementation would generate the token, cache it, and reuse it for all subsequent requests with that email address, even against the sandbox.
Handling expiration and errors
Tokens don’t last forever; as a security mechanism, they only last up to two weeks. Do bear in mind, though, that this doesn’t mean they’ll last a full two weeks: Authorization tokens can at any time be revoked for any number of reasons (usually for security). If a token has been revoked, you’ll get back an AuthenticationError with the reason GOOGLE_ACCOUNT_COOKIE_INVALID.
Most of these errors can be handled simply by requesting a new authorization token, but if you get back a CaptchaRequired error when performing the ClientLogin interactions, you’ll need the user to resolve the CAPTCHA before you’re allowed generation of new tokens (or wait approximately 5 minutes, after which it will work again). The error message will include a URL to the image and a CAPTCHA token, so you can embed this directly into your application, without having to redirect the user to a web page. Check the ClientLogin documentation for details.
What to keep in mind when implementing your application
When implementing your application, keep these best practices in mind:
- Generate a new token before the first request your application makes. You’ll need a token for every different email header that you use, so:
- if you log in by setting the email header to your MCC (My Client Center) account and then change the clientEmail header to the different accounts you’re accessing, you’ll only need a single token;
- if you log in by setting the email and password headers directly to those of the different accounts you’re accessing, you’ll need a new token for each.
- Reuse this token in subsequent requests.
- If you receive an AuthenticationError back, take a look at the reason:
- if it indicates an expired token, try generating a new one and proceeding;
- if it indicates an unrecoverable error, present the information to the user, and let them decide how to proceed.
Finally, if you’re using one of our client libraries, then we have good news for you: the first two steps are already taken care of! Just set your credentials according to the instructions for your specific client library, and it will manage both v13 and v2009 authorization for you.
Keep in mind that if you have any further questions or run into any other authorization issues, the documentation and the forum are the right place to go!
--Sérgio Gomes, AdWords API Team
