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
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.
- 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.
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.
The general steps that you perform to migrate an app on a domain are these:
- Verify the prerequisites: both old and new apps are published, scopes match
- Note some info you will need: listing ID, user key and secret, and active domains
- Associate the old and new apps and make sure they share owner
- 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:
- Make a note of the consumer key and consumer key secret.
- In the old G Suite Marketplace listing, click "View OAuth Consumer Key" to display the pop-up shown below
- Note the consumer key, which has the format: xxxxxxxxxx.apps.googleusercontent.com
- Note the consumer key secret, which is an alphanumeric string
These are shown in the following screenshot:
- 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:
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:
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.
|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.
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).
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.
COB scopes are same for both OAuth 1.0 and OAuth 2.0.
- 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|