Requesting permissions for API use in add-ins

This article describes the different permission levels that you declare in your add-in's manifest to specify the level of JavaScript API access your add-in requires for its features.

Important

This article applies to only non-Outlook add-ins. To learn about permission levels for Outlook add-ins, see Outlook permissions model.

Permissions model

A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your add-ins. The following figure shows the five levels of API permissions you can declare in your add-in's manifest.

These permissions specify the subset of the API that the add-in runtime allows your add-in to use when a user inserts, and then activates (trusts) your add-in. To declare the permission level your add-in requires, specify one of the permission values in the manifest. The markup varies depending on the type of manifest.

• Unified manifest for Microsoft 365: Use the "authorization.permissions.resourceSpecific" property. The following example requests the write document permission, which allows only methods that can write to (but not read) the document.

  "authorization": {
      "permissions": {
        "resourceSpecific": [
          ...
          {
            "name": "Document.Write.User",
            "type": "Delegated"
          },
        ]
      }  
  },
  

  Note

  The unified manifest for Microsoft 365 can be used in production Outlook add-ins. It's available only as a preview for Excel, PowerPoint, and Word add-ins.

• Add-in only manifest: Use the Permissions element of the manifest. The following example requests the write document permission, which allows only methods that can write to (but not read) the document.

  <Permissions>WriteDocument</Permissions>
  

As a best practice, you should request permissions based on the principle of least privilege. That is, you should request permission to access only the minimum subset of the API that your add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the read document permission.

The following table describes the subsets of the Common and Application-specific JavaScript APIs that are enabled by each permission level.

Permission canonical name	Add-in only manifest name	Unified manifest name	Enabled subset of the Application-specific APIs	Enabled subset of the Common APIs
restricted	Restricted	Document.Restricted.User	None	The methods of the Settings object, and the Document.getActiveViewAsync method. This is the minimum permission level that can be requested by an add-in.
read document	ReadDocument	Document.Read.User	All and only APIs that read the document or its properties.	In addition to the API allowed by the restricted permission, adds access to the API members necessary to read the document and manage bindings. This includes the use of: The Document.getSelectedDataAsync method to get the selected text, HTML (Word only), or tabular data, but not the underlying Open Office XML (OOXML) code that contains all of the data in the document. The Document.getFileAsync method to get all of the text in the document, but not the underlying OOXML binary copy of the document The Binding.getDataAsync method for reading bound data in the document. The addFromNamedItemAsync, addFromPromptAsync, and addFromSelectionAsync methods of the Bindings object for creating bindings in the document. The getAllAsync, getByIdAsync, and releaseByIdAsync methods of the Bindings object for accessing and removing bindings in the document. The Document.getFilePropertiesAsync method to access document file properties, such as the URL of the document. The Document.goToByIdAsync method to navigate to named objects and locations in the document. For task pane add-ins for Project, all of the "get" methods of the ProjectDocument object.
read all document	ReadAllDocument	Document.ReadAll.User	Same as read document.	In addition to the API allowed by the restricted and read document permissions, allows the following additional access to document data. The Document.getSelectedDataAsync and Document.getFileAsync methods can access the underlying OOXML code of the document (which in addition to the text may include formatting, links, embedded graphics, comments, revisions, and so forth).
write document	WriteDocument	Document.Write.User	All and only APIs that write to the document or its properties.	In addition to the API allowed by the restricted permission, adds access to the following API members. The Document.setSelectedDataAsync method to write to the user's selection in the document.
read/write document	ReadWriteDocument	Document.ReadWrite.User	All Application-specfic APIs, including those that subscribe to events.	In addition to the API allowed by the restricted, read document, read all document, and write document permissions, includes access to all remaining API supported by add-ins, including methods for subscribing to events. You must declare the read/write document permission to access these additional API members: The Binding.setDataAsync method for writing to bound regions of the document The TableBinding.addRowsAsync method for adding rows to bound tables. The TableBinding.addColumnsAsync method for adding columns to bound tables. The TableBinding.deleteAllDataValuesAsync method for deleting all data in a bound table. The setFormatsAsync, clearFormatsAsync, and setTableOptionsAsync methods of the TableBinding object for setting formatting and options on bound tables. All of the members of the CustomXmlNode, CustomXmlPart, CustomXmlParts, and CustomXmlPrefixMappings objects All of the methods for subscribing to the events supported by add-ins, specifically the addHandlerAsync and removeHandlerAsync methods of the Binding, CustomXmlPart, Document, ProjectDocument, and Settings objects.

See also

• Privacy and security for Office Add-ins