Google Analytics

Management API - Authorization

The document describes how an application can gain authorization to access data through the Core Reporting API version 3.0.

  1. Authorizing Requests
  2. Common OAuth 2.0 Flows
  3. Troubleshooting

Authorizing Requests

Before users can view their account information on the Google Analytics web site, they must first log in with a Google Account. In the same way, when users first access your application, they need to authorize your application to access their data.

Every request your application sends to the Management 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.

The Management API also supports older authorization options, such as OAuth 1.0, AuthSub, or ClientLogin; however, in most cases we don't recommend using those other options. If your application already uses those options, we recommend migrating to OAuth 2.0 if possible.

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. To find your application's API key:

  1. Go to the Google Developers Console.
  2. Select a project.
  3. In the sidebar on the left, select APIs & auth. In the list of APIs, make sure the status is ON for the Management API.
  4. In the sidebar on the left, select Credentials.
  5. The API supports two types of credentials. Create whichever credentials are appropriate for your project:
    • OAuth 2.0: Your application must send an OAuth 2.0 token with any request that accesses private user data. Your application sends a client ID and, possibly, a client secret to obtain a token. You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.

    • Public API keys: A request that does not provide an OAuth 2.0 token must send an API key. The key identifies your project and provides API access, quota, and reports. If the key type you need does not already exist, create an API key by selecting Create New Key and then selecting the appropriate key type. Then enter the additional data required for that key type.

Authorizing requests with OAuth 2.0

All requests to the Management 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 using the Google Developers Console. Google then provides information you'll need later, such as a client ID and a client secret.
  2. Activate the Management API in the Google Developers Console. (If the API isn't listed in the Developers 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 a consent screen 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 Management API:

Scope Meaning
https://www.googleapis.com/auth/analytics.readonly Read-only access to the Analytics API.
https://www.googleapis.com/auth/analytics Write access to the Analytics API.
https://www.googleapis.com/auth/analytics.manage.users View and manage user permissions for Analytics accounts.

To request access using OAuth 2.0, your application needs the scope information, as well as information that Google supplies when you register your application (such as the client ID and 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 page with libraries and samples for more details.

Note: While we recommend migrating to OAuth 2.0, version 2.4 does support legacy authorization mechanisms. If you use AuthSub or OAuth 1.0, you should use the same OAuth 2.0 scope.

Common OAuth 2.0 Flows

The following guidelines outline common use cases for specific OAuth 2.0 flows:

Web Server

This flow is good for automated/offline/scheduled access of a user's Google Analytics data.

Example:
  • Automatically updating user dashboards with the latest Google Analytics data.

Client-side

Ideal for when users interact directly with the application to access their Google Analytics data within a browser. This flow eliminates the need for server-side capabilities, but it also makes it impractical for automated/offline/scheduled reporting.

Example:

Installed Apps

For applications that are distributed as a package and installed by the user. It requires that the application or user have access to a browser to complete the authentication flow.

Examples:
  • A desktop widget on a PC or Mac.
  • A plugin for a content management system — The benefit of this flow compared to web server or client-side is that a single Developers Console project can be used for your application. This allows for consolidated reporting and a simpler installation for users.

Service Accounts

Useful for automated/offline/scheduled access to Google Analytics data for your own account. For example, to build a live dashboard of your own Google Analytics data and share it with other users.

There are a few steps you need to follow to configure service accounts to work with Google Analytics:

If you haven't already registered your application with the Google Developers Console, then set up a project and application in the Developers Console. The system guides you through the process of choosing or creating a project and registering a new application, and it automatically activates the API for you.

If you've already registered your application with the Developers Console, then follow this procedure instead:

  1. Go to the Google Developers Console.
  2. Select a project, or create a new one.
  3. In the sidebar on the left, select APIs & auth. In the list of APIs, make sure the status is ON for the Management API.
  4. In the sidebar on the left, select Credentials.

In either case, you end up on the application's credentials page.

To set up a service account, select Create New Client ID. Specify that your application type is service account, and then select Create Client ID. A dialog box appears; to proceed, select Okay, got it. (If you already have a service account, you can add a new key by selecting Generate new key beneath the existing service-account credentials. A dialog box appears; to proceed, select Okay, got it.)

Troubleshooting

If you are having issues with authentication and are getting 401 or 403 status codes here are a couple of steps you can take to troubleshoot your issues:

You will get a 401 status code if your access_token has expired or if you are using the wrong scope for the API.

You will get a 403 status code if the authorized user does not have access to the view (profile). Make sure you are authorized with the correct user and that they indeed have the view (profile) you have selected.

OAuth 2.0 playground. This is a fantastic tool that allows you to go through the entire authorization flow through a web interface. The tool also displays all the HTTP request headers required for making an authorized query. If you can't get authorization to work in your own application, you should try to get it working through the OAuth 2.0 playground. Then you can compare the HTTP headers and request from the playground to what your application is sending Google Analytics. This check is a simple way to ensure you are formatting your requests properly.

OAuth 1.0 Playground. This is similar to the OAuth 2.0 playground, but for the previous version of OAuth.

Invalid Grant

If you receive an invalid_grant error response when attempting to use a refresh token, the cause of the error may be due to the following reasons:

  1. Your server's clock is not in sync with NTP.
  2. The refresh token limit has been exceeded.
    Applications can request multiple refresh tokens to access a single Google Analytics account. For example, this is useful in situations where a user wants to install an application on multiple machines and access the same Google Analytics account. In this case, two refresh tokens are required, one for each installation. When the number of refresh tokens exceeds the limit, older tokens become invalid. If the application attempts to use an invalidated refresh token, an invalid_grant error response is returned. The limit for each unique pair of OAuth 2.0 client and Google Analytics account is 25 refresh tokens (note that this limit is subject to change). If the application continues to request refresh tokens for the same Client/Account pair, once the 26th token is issued, the 1st refresh token that was previously issued will become invalid. The 27th requested refresh token would invalidate the 2nd previously issued token and so on.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.