Users must install and authorize an add-on before they can open and use it. Since these steps are the first part of the add-on user experience, you should understand them before you start creating your own add-ons.

This documentation section describes how users can install, authorize, and start using add-ons.

Before you can use an add-on, you must install it. Once installed, the add-on becomes available in the Google Workspace host application it extends.

You can install published add-ons from the Google Workspace host application or from the Google Workspace Marketplace. Domain administrators can also install add-ons on behalf of their users from the Google Workspace Marketplace. You can also install unpublished add-ons you're developing so that you can test them. Before you can use an installed add-on for first time, you must authorize it.

For more details, see Publish add-ons.

After installing an add-on, it becomes available in the Google Workspace host application it extends. The first time a user attempts to use the add-on the host application presents them with an authorization card or dialog. This card explains what the add-on needs permission to do for the user, such as accessing the content of the current Google Sheet. The user can then grant those permissions and allow the add-on to proceed. If the user denies the add-on authorization, they can't use the add-on.

Editor add-ons use an authorization model that differs from Google Workspace add-ons. Because Editor add-ons operate on Google Drive files, the editor authorization model defines various authorization modes that result when add-ons are used with individual files. When developing Editor add-ons, it's important to understand the different modes and how an add-on moves between them.

Authorize published add-ons

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

1. You are prompted to Choose an account to 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 want to grant authorization, click Allow. This enables the add-on for use.
3. You can now run it from the host application 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.

Authorize unpublished Google Workspace add-ons

Unpublished add-ons don't have the same authorization flow as published add-ons because they aren't listed in the Google Workspace 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.

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.

Authorize non-Google services for a Google Workspace add-on

It's possible for a Google Workspace add-on to connect to a third-party service that itself requires authorization. Google Workspace add-ons that connect to such 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 a Google Workspace 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.

For more information, refer to Connect your Google Workspace add-on to a third-party service.

Third-party conferencing systems

Google Workspace add-ons that extend Google Calendar can also add additional conferencing solutions that let users select a third-party conferencing system when editing Google Calendar events. If your add-on provides conferencing options that require the user to log into them, your add-on must give the user the ability to do so.

If a user attempts to create a conference with your add-on without a necessary sign in, the conference solutions's onCreateFunction method should return a ConferenceData object containing an ConferenceError with an authentication URL.

Upon receiving this object, Google Calendar creates a LOG IN button in the event edit UI that links to the authentication URL the add-on provides. Users can then use this button to log into the third-party system prior to using the add-on further.

See Creating third-party conferences for more details on handling authorization using ConferenceError.

Authorize unpublished Editor add-ons

It's a best practice to test Editor add-ons as you develop them. The authorization flow is identical to that for published Editor 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.

Unauthorize add-ons

When developing add-ons, it can be useful to unauthorize them so you can retest 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.

When you run the add-on again after unauthorizing it, the authorization flow is presented again.

Uninstall add-ons

To uninstall an add-on that you installed from the Google Workspace Marketplace, refer to Uninstall a Marketplace app or add-on.

To uninstall an unpublished add-on built in Apps Script, refer to Uninstall an unpublished add-on.

• Open and use installed add-ons
• Connect your Google Workspace add-on to a third-party service