Set up and use OAuth

All Local Services API calls must be authorized through OAuth 2.0. This lets your Local Services API client app access a user's Local Services Ads account without the need to handle or store the user's login information.

The Local Services API uses the OAuth 2.0 protocol to authenticate users. To learn more about OAuth 2.0, see Using OAuth 2.0 to Access Google APIs.

Configure a Google API Console Project for the Local Services API

To authenticate and authorize Google Ads users, you must have credentials to access Google's OAuth 2.0 servers. These credentials identify your application to Google and let you generate OAuth tokens to manage Google Ads users. Use the Google API Console to manage access to your Google OAuth 2.0 credentials.

To receive these credentials, perform the following steps:

  1. Create a project. To do so, navigate to the Google API Console. Click Create project, enter a name, and click Create.

  2. Enable the Local Services API in your project:

    1. Open the API Library in the Google API Console. If prompted, select your project or create a new one. The API Library lists all of the available APIs, grouped by product family and popularity.

      If the Local Services API isn't visible in the list, use the search box to find it.

    2. Select the Local Services API, then click Enable.

  3. Choose an app type. The Local Services API uses the same app types as the Google Ads API. For more details on which app type to use, see Choose an app type.

  4. Create a client ID and client secret. For the Local Services API, follow the same steps to create a client ID and client secret as used for the Google Ads API. The steps are identical for both use cases.

Use the Client Library to obtain OAuth 2.0 tokens

For a list of client libraries you can use to make OAuth 2.0 authorization requests, see Client libraries. Follow the library-specific instructions to learn how to use a refresh token to obtain a new access token.

How to obtain an OAuth 2.0 refresh token

We recommend that you use the client libraries in production to authenticate users. If you want to use an HTTP client for testing purposes, use the following instructions to obtain an OAuth 2.0 refresh token and an access token. Steps 1, 2, and 3 are one-time setup instructions that you must manually perform, and steps 4 and 5 can be automated afterwards to run without human intervention, such as a cron job.

  1. Download and install curl, a command line tool to make HTTP web requests.

  2. Follow the instructions on the OAuth Playground page to obtain an OAuth 2.0 refresh token. Use the following scope for the Local Services API:

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

    This is the same OAuth 2.0 scope used by the Google Ads API.

    At the end of this step, you receive two tokens: a refresh token and an access token. Save both of them.

  3. Run the following command on a command prompt to verify that the previous step was successful:

    curl https://oauth2.googleapis.com/tokeninfo?access_token=<INSERT_ACCESS_TOKEN>

    If the command output displays a message like the following, it was successful:

    {
  "azp": "************-********************************.apps.googleusercontent.com",
  "aud": "************-********************************.apps.googleusercontent.com",
  "scope": "https://www.googleapis.com/auth/adwords [googleapis.com]",
  "exp": "1611183382",
  "expires_in": "3482",
  "access_type": "offline"
}

    If there's an error or the scope isn't correct, try to generate the tokens again.

  4. Generate a new access token without manual intervention. This is important because access tokens expire hourly. Refresh tokens take much longer to expire, so you often need to manually revoke them when they're no longer needed.

    To get a new access token, run the following command:

    curl --data "refresh_token=<INSERT_REFRESH_TOKEN>&client_id=<INSERT_CLIENT_ID>&client_secret=<INSERT_CLIENT_SECRET>&grant_type=refresh_token" -X POST "https://oauth2.googleapis.com/token”

  5. Run the following API call:

    curl -H "Authorization: Bearer <INSERT_ACCESS_TOKEN>" https://localservices.googleapis.com/v1/accountReports:search?query=manager_customer_id:<INSERT_10_DIGIT_MANAGER_CUSTOMER_ID_WITHOUT_HYPHENS>

    If this call succeeds, your setup is complete.