G Suite Marketplace: using the UpgradeableApp API resource

Note: End-of-life warning -- This API is provided for a limited time to help developers migrate their OAuth 1.0 G Suite Marketplace apps to OAuth 2.0 with the new Chrome Web Store listing style. Expect the API to be removed by late 2014.

The UpgradeableApp API resource is for developers who have existing OAuth 1.0 applications listed on the G Suite Marketplace. It provides a way to upgrade these apps to use OAuth 2.0 authentication for a given domain. When you use the resource's update method, the following actions are performed:

  • Install the new version of the app onto the domain
  • Uninstall old version's app listing
  • Grant OAuth 2.0 scopes (only scopes which are equivalent to OAuth 1.0 granted scopes)
  • Revoke OAuth 1.0 scope grants
  • Copy service on/off service setting from the old listing to the new version of the app.
  • Send an admin notification to the upgraded domain
  • Trigger migration of apps reviews from the old marketplace to the new Chrome Web Store listing (it may take up to 24 hours to reflect after domain upgrade)

Because this API method works on a per-domain basis, you can decide who to upgrade, and migrate them when you want: you can set up, migrate, and test one domain at a time.

Note: You should normally set up a test domain with the OAuth 1.0 app installed on it and try migrating that domain first.

Advisories

  • Quota: do not issue more than 1 query per two seconds (0.5 qps)
  • End of life: this API will be available until the end of Q3 2014
  • OAuth 1.0: access to this API requires OAuth 1.0 authentication. See Auth Model for details.
  • Mapping: You need to map your new OAuth 2.0 app to the old version using its ID in the console of the old version, as described in Step 3: Associate the two apps and their ownership. If you don't do this, the migration cannot be performed.

Prerequisites

There are several prerequisites that must be met before you can upgrade a domain to the new (OAuth 2.0) version of your app. These are described in more detail under Step 1: Verify your prerequisites.

  • You need to have a currently published and installable app on the old Google Apps Marketplace dashboard.
  • You need to have the new app published and installable on the new G Suite Marketplace dashboard.
  • The scopes for the new and old apps must be compatible.

Steps

The general steps that you perform to migrate an app on a domain are these:

  1. Verify the prerequisites: both old and new apps are published, scopes match
  2. Note some info you will need: listing ID, user key and secret, and active domains
  3. Associate the old and new apps and make sure they share owner
  4. Invoke the API method, using the info from step three to form the URI

The following sections describe these steps in detail.

Step 1: Verify your prerequisites

There are several prerequisites that must be met before you can upgrade a domain to the new (OAuth 2.0) version of your app.

  • Make sure that the old version of your app is currently published and installable on the old G Suite Marketplace dashboard. An app that was only in test, or which has been taken down and is no longer installable from the dashboard, cannot be migrated.

  • Make sure that the new version of your app is published and installable on the new G Suite Marketplace dashboard.

  • Make sure that the scopes for the new and old apps are compatible. The new version of the app must either use the same scopes as the old version, or use equivalent scopes. Equivalent scopes are described in the scope matching section.

Step 2: Gather some information you'll need

You'll need to gather the marketplace listing ID, the consumer key and its secret, and the list of domains on which the old version of your app is installed.

  • Make a note of marketplace listing ID. This will be in the format xxxx:xxxxxxxxxxxxxx as shown in URL of the following screenshot:

alt text

  • Make a note of the consumer key and consumer key secret.
    1. In the old G Suite Marketplace listing, click "View OAuth Consumer Key" to display the pop-up shown below
    2. Note the consumer key, which has the format: xxxxxxxxxx.apps.googleusercontent.com
    3. Note the consumer key secret, which is an alphanumeric string

These are shown in the following screenshot:

alt text

  • Make a list of all the domains where the old version of your app is installed. You will use this list to iterate over the domains, migrating one domain at a time as described in step 4 of these instructions.

Step 3: Associate the two apps and their ownership

The two apps must be associated by providing a link to the new app in the old app's dashboard, and the old app's owner must be a member of the new app's project.

  • Link the two apps by entering the Chrome Web Store item ID of the new app into the dashboard of the old app, as shown in the following screenshot:

alt text

Step 4: Invoke the API method

To perform the migration of one domain, you need the following information that you gathered earlier. You'll use the following three items to form the REST method call:

  • listingID — The old apps marketplace listing ID
  • cwsID — The new Chrome Web Store item ID
  • domain — The domain name to migrate with this invocation

You'll also need the consumer key and secret, to use with OAuth 1.0 authentication of the call (see Auth Model for further details about authenticating this call)

With this information in hand, invoke the following PUT method:

PUT https://www.googleapis.com/appsmarket/v2/upgradableApp/listingID/cwsID/domain

The response to a call to this method call will include an upgrade_status field indicating the outcome of the migration. The upgrade_status field will contain one of the following values:

  • SUCCESS - The domain was migrated successfully: the old OAuth 1.0 app has been uninstalled and the new OAuth 2.0 app has been installed. Furthermore, all scopes for the new OAuth 2.0 app have been granted.
  • ADMIN_ACTION_REQUIRED - The domain was migrated successfully: the old OAuth 1.0 app has been uninstalled and new OAuth 2.0 app has been installed. However, there were scopes NOT granted for the new OAuth 2.0 app.
    Note: This can happen when developers add new auth and Contextual Gadget scopes to their old app (a) after it was installed on the domain, and (b) these were never granted from the admin console.
  • FAILED - An error has occurred. An error message will also be included in response.

The upgrade status values and their associated error codes/messages are shown in the following table.

Status ErrorCode Error Message
SUCCESS NA NA
ADMIN_ACTION_REQUIRED NA NA
FAILED REQUIRED You must specify marketplace listing id.
FAILED REQUIRED You must specify cws item id.
FAILED REQUIRED You must specify domain name.
FAILED INVALID_VALUE Invalid marketplace listing id listingId.
FAILED INVALID_VALUE Invalid domain name domainName.
FAILED INVALID_VALUE Invalid Chrome Web Store item cwsItemId.
FAILED CONDITION_NOT_MET OAuth 2.0 upgrade has not been enabled yet * This error message means the new app ID has not been mapped to the old app in the vendor console.
FAILED CONDITION_NOT_MET Chrome Web Store item cwsItemId specified in vendor console does not match with Chrome Web Store item id cwsItemId passed to API call.
FAILED CONDITION_NOT_MET Marketplace listing id listingId has already been upgraded to Chrome Web Store item cwsItemId for domain domainName.
FAILED CONDITION_NOT_MET Chrome Web Store item cwsItemId in current invocation does not match with Chrome Web Store item cwsItemId in earlier UpgradableApp api invocation for domain domainName.
FAILED CONDITION_NOT_MET Marketplace listing id listingId with app id apiConsoleProjectId is not installed for domain domainName.
FAILED CONDITION_NOT_MET Marketplace listing listingId vendor is not an owner for Chrome Web Store item cwsItemId.
FAILED CONDITION_NOT_MET Marketplace listing id listingId is not an installable listing.
FAILED CONDITION_NOT_MET AppId devconsoleId for listing id listingId is not OAuth 1.0 enabled.
FAILED CONDITION_NOT_MET AppId devconsoleId for Chrome Web Store item cwsItemId is not OAuth 2.0 enabled.
FAILED CONDITION_NOT_MET App console id for Chrome Web Store item cwsItemId is not domain installable.
FAILED CONDITION_NOT_MET Chrome Web Store item id cwsItemId is not associated with api console project.
FAILED CONDITION_NOT_MET Chrome Web Store item cwsItemId is not published yet.

**Note: **If a new OAuth 2.0 version of the app is already installed for the given domain — the admin may already have installed it in some other way — then API will just uninstall the OAuth 1.0 app. In this case no action will be done for OAuth 2.0 app.

Auth Model

Access to the UpgradableApp API is authorized using OAuth 1.0**. **All requests to the API must be signed using 2-legged OAuth, using the consumer key and consumer key secret for the old OAuth 1.0 app (obtained in Step 2 above).

Scope equivalency/mapping

Developers who wants to use upgrade feature, should use either exactly same scopes or equivalent scopes.

Scopes for Single Sign On
If the old OAuth 1.0 app has OPEN_ID_REALM extension defined and open id realm extension is enabled for the domain, following scopes will be granted during upgrade.

  • https://www.googleapis.com/auth/userinfo.email
  • https://www.googleapis.com/auth/userinfo.profile

COB Scopes
COB scopes are same for both OAuth 1.0 and OAuth 2.0.

AUTH Scopes

  • Some of the auth scopes work with both OAuth 1.0 and OAuth 2.0 flows. These scopes can be added to the new app with no change.
  • Auth scopes which are very specific to OAuth 1.0 cannot be added to the new app using the API console. For these scopes there are equivalent OAuth 2.0 scopes that can be added to new app, as shown in the following table.
OAuth 1.0 scope OAuth 2.0 scope
https://docs.google.com/feeds/ http://docs.google.com/feeds/ https://www.googleapis.com/auth/drive
https://docs.google.com/feeds/ http://docs.google.com/feeds/ https://www.googleapis.com/auth/drive.file
https://docs.google.com/feeds/ http://docs.google.com/feeds/ https://www.googleapis.com/auth/drive.readonly
https://apps-apis.google.com/a/feeds/group/#readonly https://www.googleapis.com/auth/admin.directory.group.readonly
https://apps-apis.google.com/a/feeds/policies/#readonly https://www.googleapis.com/auth/admin.directory.orgunit.readonly
https://apps-apis.google.com/a/feeds/user/#readonly https://apps-apis.google.com/a/feeds/nickname/#readonly https://www.googleapis.com/auth/admin.directory.user.readonly

Send feedback about...

G Suite Marketplace
G Suite Marketplace
Need help? Visit our support page.