Version v4 of the Google Sheets API is now available! This migration guide shows how to update applications to use v4.

Authorize Requests

When your application requests non-public user data, it must include an authorization token. The token also identifies your application to Google.

About authorization protocols

You must use OAuth 2.0 to authorize requests.

Authorize requests with OAuth 2.0

Requests to the Google Sheets API for non-public user data 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. When your application needs access to user data, it asks Google for a particular scope of access.
  3. Google displays an OAuth dialog to the user, asking them to authorize your application to request some of their data.
  4. If the user approves, then Google gives your application a short-lived access token.
  5. Your application requests user data, attaching the access token to the request.
  6. 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 Google Sheets API:

https://spreadsheets.google.com/feeds

Additionally, if an application needs to create spreadsheets, or otherwise manipulate their metadata, then the application must also request a Google Drive API scope; see Choose Auth Scopes for information about the available scopes in Google Drive API v2.

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).

Perform OAuth 2.0

.NET

The following example is copied from the google-gdata project's sample directory. It has been modified to accommodate the Sheets API, and is provided here for ease of reference.

using System;
using Google.GData.Client;
using Google.GData.Spreadsheets;

namespace MySpreadsheetIntegration
{
  class Program
  {
    static void Main(string[] args)
    {
      ////////////////////////////////////////////////////////////////////////////
      // STEP 1: Configure how to perform OAuth 2.0
      ////////////////////////////////////////////////////////////////////////////

      // TODO: Update the following information with that obtained from
      // https://code.google.com/apis/console. After registering
      // your application, these will be provided for you.

      string CLIENT_ID = "12345678.apps.googleusercontent.com";

      // This is the OAuth 2.0 Client Secret retrieved
      // above.  Be sure to store this value securely.  Leaking this
      // value would enable others to act on behalf of your application!
      string CLIENT_SECRET = "Gc0230jdsah01jqpowpgff";

      // Space separated list of scopes for which to request access.
      string SCOPE = "https://spreadsheets.google.com/feeds https://docs.google.com/feeds";

      // This is the Redirect URI for installed applications.
      // If you are building a web application, you have to set your
      // Redirect URI at https://code.google.com/apis/console.
      string REDIRECT_URI = "urn:ietf:wg:oauth:2.0:oob";

      ////////////////////////////////////////////////////////////////////////////
      // STEP 2: Set up the OAuth 2.0 object
      ////////////////////////////////////////////////////////////////////////////

      // OAuth2Parameters holds all the parameters related to OAuth 2.0.
      OAuth2Parameters parameters = new OAuth2Parameters();

      // Set your OAuth 2.0 Client Id (which you can register at
      // https://code.google.com/apis/console).
      parameters.ClientId = CLIENT_ID;

      // Set your OAuth 2.0 Client Secret, which can be obtained at
      // https://code.google.com/apis/console.
      parameters.ClientSecret = CLIENT_SECRET;

      // Set your Redirect URI, which can be registered at
      // https://code.google.com/apis/console.
      parameters.RedirectUri = REDIRECT_URI;

      ////////////////////////////////////////////////////////////////////////////
      // STEP 3: Get the Authorization URL
      ////////////////////////////////////////////////////////////////////////////

      // Set the scope for this particular service.
      parameters.Scope = SCOPE;

      // Get the authorization url.  The user of your application must visit
      // this url in order to authorize with Google.  If you are building a
      // browser-based application, you can redirect the user to the authorization
      // url.
      string authorizationUrl = OAuthUtil.CreateOAuth2AuthorizationUrl(parameters);
      Console.WriteLine(authorizationUrl);
      Console.WriteLine("Please visit the URL above to authorize your OAuth "
        + "request token.  Once that is complete, type in your access code to "
        + "continue...");
      parameters.AccessCode = Console.ReadLine();

      ////////////////////////////////////////////////////////////////////////////
      // STEP 4: Get the Access Token
      ////////////////////////////////////////////////////////////////////////////

      // Once the user authorizes with Google, the request token can be exchanged
      // for a long-lived access token.  If you are building a browser-based
      // application, you should parse the incoming request token from the url and
      // set it in OAuthParameters before calling GetAccessToken().
      OAuthUtil.GetAccessToken(parameters);
      string accessToken = parameters.AccessToken;
      Console.WriteLine("OAuth Access Token: " + accessToken);

      ////////////////////////////////////////////////////////////////////////////
      // STEP 5: Make an OAuth authorized request to Google
      ////////////////////////////////////////////////////////////////////////////

      // Initialize the variables needed to make the request
      GOAuth2RequestFactory requestFactory =
          new GOAuth2RequestFactory(null, "MySpreadsheetIntegration-v1", parameters);
      SpreadsheetsService service = new SpreadsheetsService("MySpreadsheetIntegration-v1");
      service.RequestFactory = requestFactory;

      // Make the request to Google
      // See other portions of this guide for code to put here...
    }
  }
}

Specify a version

Every request sent to the Google Sheets API can optionally specify that the request is for version 3.0 of the API, although this is not necessary.

HTTP

To specify a version number, use the GData-Version HTTP header.

GData-Version: 3.0

Alternatively, version 3.0 can be specified as a URL parameter.

https://spreadsheets.google.com/feeds/spreadsheets/private/full?v=3.0

Java

Version 3.0 is specified by default in the GData Java client library. Java developers do not need to do anything to specify a version.

In the rare circumstance an application may need to specify another version, the line of code to do so reads:

SpreadsheetService service = new SpreadsheetService("MySpreadsheetIntegration");
service.setProtocolVersion(SpreadsheetService.Versions.V3);
//service.setProtocolVersion(SpreadsheetService.Versions.V2);
//service.setProtocolVersion(SpreadsheetService.Versions.V1);

Python

Version 3.0 is specified by default in the GData Python client library. Python developers do not need to do anything to specify a version.

.NET

Version 3.0 is specified by default in the GData .NET client library. .NET developers do not need to do anything to specify a version.

Send feedback about...

Sheets API v3
Sheets API v3