Important: ClientLogin and OAuth1.0a have been officially deprecated as of April 20, 2012. They will continue to work as per our deprecation policy, but we encourage you to migrate to OAuth 2.0 as soon as possible.

All AdWords API calls must be authenticated through either OAuth or ClientLogin.

• OAuth - the recommended option. Although this is more complex to implement, it has the advantage of increased security and no token expiration.
• ClientLogin - simpler to implement, but requires your application to handle the user's name and password directly. You will also need to deal with authentication token expirations and CAPTCHA challenges.

You can see examples of both authentication systems in the client libraries.

Using OAuth

OAuth is an open standard for allowing users to authenticate third party applications to use web services on their behalf. AdWords API supports this form of authentication, enabling web applications to access a user's account without having to handle or store the user's username or password.

AdWords API supports OAuth 2.0 and OAuth 1.0a.

OAuth 2.0

Every request your application sends to the AdWords API must include an authorization token. The token also identifies your application to Google.

About authorization protocols

We recommend using OAuth 2.0 to authorize requests.

If your application has certain unusual authorization requirements, such as logging in at the same time as requesting data access (hybrid) or domain-wide delegation of authority (2LO), then you cannot currently use OAuth 2.0 tokens. In such cases, you must instead use OAuth 1.0 tokens and an API key. You can find your application's API key in the Google APIs Console, in the Simple API Access section of the API Access pane.

Authorizing requests with OAuth 2.0

All requests to the AdWords API must be authorized by an authenticated user.

The details of the authorization process, or "flow," for OAuth 2.0 vary somewhat depending on what kind of application you're writing. The following general process applies to all application types:

1. When you create your application, you register it with Google. Google then provides information you'll need later, such as a client ID and a client secret.
2. Activate the AdWords API in the Services pane of the Google APIs Console. (If it isn't listed in the Console, then skip this step.)
3. When your application needs access to user data, it asks Google for a particular scope of access.
4. Google displays an OAuth dialog to the user, asking them to authorize your application to request some of their data.
5. If the user approves, then Google gives your application a short-lived access token.
6. Your application requests user data, attaching the access token to the request.
7. If Google determines that your request and the token are valid, it returns the requested data.

Some flows include additional steps, such as using refresh tokens to acquire new access tokens. For detailed information about flows for various types of applications, see Google's OAuth 2.0 documentation.

Here's the OAuth 2.0 scope information for the AdWords API:

To request access using OAuth 2.0, your application needs the scope information, as well as information that Google supplies during application registration (such as the client ID and/or the client secret).

Tip: The Google APIs client libraries can handle some of the authorization process for you. They are available for a variety of programming languages; check the Libraries and Samples page for more details.

You can pass the token in the Authorization HTTP header as: Authorization: Bearer ...

To learn more about OAuth 2.0, try out the OAuth2 Playground.

OAuth 1.0

The OAuth 1.0 protocol is fairly complex, and Google's implementation introduces some other requirements. Read OAuth 1.0 for Web Applications carefully before using OAuth 1.0.

The OAuth 1.0 system requires several pieces of data to be added to all your API requests, including a token and a signature. You can pass information as URL parameters or through the Authorization HTTP request header.

Learning about OAuth1.0a

To learn about OAuth1.0a try out the Google OAuth1.0a Playground as follows:

• In Step 1, set the Scope to https://adwords.google.com/api/adwords/
• In Step 2:
  • Set oauth_signature_method set to HMAC-SHA1.
  • Set oauth_consumer_key to anonymous.
  • Set consumer secret to anonymous
• In Step 3, select Request token. This passes the parameters you specified above to the Google Accounts server located at https://www.google.com/accounts/OAuthGetRequestToken, and returns a Request Token.
• In Step 4, select Authorize to authorize the returned Request Token. This redirects the browser to a Google Accounts web page, from which you click a button that says you authorize the access to your data. On the page that follows, select Grant access to grant access to this website. This will return you to the playground page, and generate a new oauth_token_secret and oauth_token.
• In Step 5, select Access Token to upgrade to an Access Token. The access token has the same format as the Request Token shown above, but has new values for each parameter.
• In Step 6, put the endpoint URL of the service you're calling into the box. Change the dropdown to POST and select enter post data to enter a POST XML request. Select Execute.

Using OAuth1.0a with the AdWords API

Once you've tried out the OAuth Playground use the API to obtain and pass an authorization key.

When your application starts using OAuth in production it should be registered with Google's domain management system. After ownership of your domain is confirmed you will be given an OAuth consumer token and consumer secret. These values are used to identify your application to Google's OAuth servers and do not expire. During development you can use the value "anonymous" for both the consumer token and the secret.

Obtaining an access token

You need an OAuth access token to make requests to the AdWords API. Obtaining a token is a multi-stage process. This process only needs to take place once per account, since the resulting access token never expires.

1. Get a request token by making an HTTP request to the OAuth server and parsing the results to retrieve the token. For the AdWords API, the scope parameter must be set to https://adwords.google.com/api/adwords/
   
   For more information see OAuthGetRequestToken.

2. Request authorization from the user by redirecting the user to Google's OAuth servers, and passing in the request token generated earlier as a query parameter. Once there, the user will log in to their Google account, grant authorization, and be redirected back to the callback URL set previously. There are no special settings needed for the AdWords API. For more information, refer to OAuthAuthorizeToken.

3. Upgrade to an access token by following the instructions in OAuthGetAccessToken. There are no special settings needed for the AdWords API.

Signing API requests

The OAuth signature is a combination of different fields, including a signature, nonce, and consumer key. When using OAuth for authorization, all requests to the AdWords API must be signed and include the OAuth access token and signature. The signature must be included in the API request as an HTTP header or a SOAP header, as described previously.

The signature must be regenerated for every request to the API and is based on the endpoint URL of the service being called. For more information, refer to Signing OAuth requests.

Using ClientLogin

ClientLogin involves requesting a token that is added to your SOAP header in all API calls. Retrieve a ClientLogin authentication token by posting your account login and password to the Google ClientLogin API. Alternatively, you can use cURL to obtain the token. An authentication token is valid for about two weeks after you acquire it. You should cache the token and reuse it for the two weeks period—frequent requests for new tokens can result in CAPTCHA challenges.

Note: You need to use an application-specific password for 2-factor accounts.

Token Requests

If you are not using one of the AdWords API client libraries, your ClientLogin token request should include the following AdWords API-specific parameter values:

You should also be prepared to handle CAPTCHA challenges.

Using the Token

All SOAP calls to the AdWords API that use ClientLogin must include your token inside an <authToken> element in the header. This header is described by the RequestHeader object defined in all AdWords API WSDLs. Here is an example header that contains a ClientLogin authentication token:

<?xml version="1.0" encoding="UTF-8"?>
  <soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns="https://adwords.google.com/api/adwords/cm/v201306">
    <soap:Header>
      <RequestHeader>
        <authToken>YOUR_AUTH_TOKEN</authToken>
        <userAgent>my-test</userAgent>
        <developerToken>YOUR_ACCOUNT_LOGIN++USD</developerToken>
        <clientCustomerId>XXX-XXX-XXXX</clientCustomerId>
      </RequestHeader>
    </soap:Header>

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.