Authorization

Add-ons require authorization from the user before they can operate. This is true of both published add-ons you installed from the G Suite Marketplace and add-ons you are developing yourself.

Authorizing published add-ons

After you install a published add-on, the authorization flow begins immediately:

  1. You are prompted to Choose an account install the add-on to.
  2. You are then presented with the list of authorizations the add-on requires to operate, so that you know what it attempts to do. Review this list carefully, and if you still wish to grant authorization, click Allow. This enables the add-on for use.
  3. You can now run it from the application (Gmail or a editor) it extends. If the application was already open in a browser tab, you may need to refresh the tab before the add-on becomes available.

If the add-on you've installed is later updated and requires additional authorizations you have not yet granted, you are prompted to provide those permissions the next time you use the add-on.

Authorizing unpublished Gmail add-ons

Add-on authorization card

Unpublished add-ons don't have the same authorization flow as published add-ons because they aren't listed in the G Suite Marketplace yet. After installing an unpublished add-on, you aren't immediately asked to authorize. Instead, the authorization flow starts when you first attempt to use the add-on. You can run the add-on by opening or composing a message in Gmail (depending on which interfaces the add-on extends). If Gmail is already open, you may need to refresh the tab before the add-on executes.

When an add-on is run, it determines if any user authorization is needed. If authorization is necessary, the add-on presents an authorization card. Authorization is always required the first time an add-on executes, and may also be required if a new version of the add-on uses a service not previously authorized. The Authorize Access button provides a dialog window for the user to Allow or Deny authorization for the add-on.

Authorizing unpublished editor add-ons

It's a best practice to test add-ons as you develop them. The authorization flow is identical to that for published add-ons, except that the flow starts when you first attempt to test the add-on. If you later retest the same add-on, you aren't prompted for authorization again.

Authorizing non-Google services

Add-ons that connect to non-Google services require two separate actions from the user:

  • Authorization of the add-on itself when the add-on is installed or first started.
  • Authorization of the non-Google service when it is first accessed.

If an add-on you are developing needs to access a non-Google service using OAuth, you must configure the connection for that service when building the add-on.

When authorization of a non-Google service is required, the add-on presents the user with an authorization prompt card for that service. You can customize this authorization prompt if you wish, or use the default card.

For more details, please refer to the Connecting to non-Google services guide.

Unauthorizing add-ons

When developing add-ons it can be useful to unauthorize them so you can test the authorization flow.

You can unauthorize an add-on by doing the following:

  1. Open your account security console.
  2. Locate and click the add-on you wish to unauthorize.
  3. Click REMOVE ACCESS.

If you try to run the add-on again after unauthorizing it, you must reauthorize before you can use it.