diff --git a/types/office-js-preview/index.d.ts b/types/office-js-preview/index.d.ts index ab866e2735..1a9e8ae910 100644 --- a/types/office-js-preview/index.d.ts +++ b/types/office-js-preview/index.d.ts @@ -13959,11 +13959,16 @@ declare namespace Office { /** * Gets a string that contains a token used to call REST APIs or Exchange Web Services. * - * The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. + * The `getCallbackTokenAsync` method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. * The lifetime of the callback token is 5 minutes. * * The token is returned as a string in the `asyncResult.value` property. * + * Calling the `getCallbackTokenAsync` method in read mode requires a minimum permission level of **ReadItem**. + * + * Calling the `getCallbackTokenAsync` method in compose mode requires you to have saved the item. + * The `saveAsync` method requires a minimum permission level of **ReadWriteItem**. + * * *REST Tokens* * * When a REST token is requested (options.isRest = true), the resulting token will not work to authenticate Exchange Web Services calls. @@ -13981,6 +13986,13 @@ declare namespace Office { * * The add-in should use the ewsUrl property to determine the correct URL to use when making EWS calls. * + * You can pass both the token and either an attachment identifier or item identifier to a third-party system. The third-party system uses + * the token as a bearer authorization token to call the Exchange Web Services (EWS) + * {@link https://docs.microsoft.com/exchange/client-developer/web-service-reference/getattachment-operation | GetAttachment} operation or + * {@link https://docs.microsoft.com/exchange/client-developer/web-service-reference/getitem-operation | GetItem} operation to return an + * attachment or item. For example, you can create a remote service to + * {@link https://docs.microsoft.com/outlook/add-ins/get-attachments-of-an-outlook-item | get attachments from the selected item}. + * * **Note**: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. * * [Api set: Mailbox 1.5] @@ -14010,21 +14022,24 @@ declare namespace Office { /** * Gets a string that contains a token used to get an attachment or item from an Exchange Server. * - * The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. + * The `getCallbackTokenAsync` method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. * The lifetime of the callback token is 5 minutes. * * The token is returned as a string in the `asyncResult.value` property. * - * You can pass the token and an attachment identifier or item identifier to a third-party system. - * The third-party system uses the token as a bearer authorization token to call the Exchange Web Services (EWS) GetAttachment or - * GetItem operation to return an attachment or item. For example, you can create a remote service to get attachments from the selected item. + * You can pass both the token and either an attachment identifier or item identifier to a third-party system. The third-party system uses + * the token as a bearer authorization token to call the Exchange Web Services (EWS) + * {@link https://docs.microsoft.com/exchange/client-developer/web-service-reference/getattachment-operation | GetAttachment} or + * {@link https://docs.microsoft.com/exchange/client-developer/web-service-reference/getitem-operation | GetItem} operation to return an + * attachment or item. For example, you can create a remote service to + * {@link https://docs.microsoft.com/outlook/add-ins/get-attachments-of-an-outlook-item | get attachments from the selected item}. * - * Your app must have the ReadItem permission specified in its manifest to call the getCallbackTokenAsync method in read mode. + * Calling the `getCallbackTokenAsync` method in read mode requires a minimum permission level of **ReadItem**. * - * In compose mode you must call the saveAsync method to get an item identifier to pass to the getCallbackTokenAsync method. - * Your app must have ReadWriteItem permissions to call the saveAsync method. + * Calling the `getCallbackTokenAsync` method in compose mode requires you to have saved the item. + * The `saveAsync` method requires a minimum permission level of **ReadWriteItem**. * - * [Api set: Mailbox 1.0] + * [Api set: Mailbox 1.0 for Read mode support; 1.3 for Compose mode support] * * @remarks * diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index f0793ff8ea..fa45a1de51 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -12265,11 +12265,16 @@ declare namespace Office { /** * Gets a string that contains a token used to call REST APIs or Exchange Web Services. * - * The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. + * The `getCallbackTokenAsync` method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. * The lifetime of the callback token is 5 minutes. * * The token is returned as a string in the `asyncResult.value` property. * + * Calling the `getCallbackTokenAsync` method in read mode requires a minimum permission level of **ReadItem**. + * + * Calling the `getCallbackTokenAsync` method in compose mode requires you to have saved the item. + * The `saveAsync` method requires a minimum permission level of **ReadWriteItem**. + * * *REST Tokens* * * When a REST token is requested (options.isRest = true), the resulting token will not work to authenticate Exchange Web Services calls. @@ -12287,6 +12292,13 @@ declare namespace Office { * * The add-in should use the ewsUrl property to determine the correct URL to use when making EWS calls. * + * You can pass both the token and either an attachment identifier or item identifier to a third-party system. The third-party system uses + * the token as a bearer authorization token to call the Exchange Web Services (EWS) + * {@link https://docs.microsoft.com/exchange/client-developer/web-service-reference/getattachment-operation | GetAttachment} operation or + * {@link https://docs.microsoft.com/exchange/client-developer/web-service-reference/getitem-operation | GetItem} operation to return an + * attachment or item. For example, you can create a remote service to + * {@link https://docs.microsoft.com/outlook/add-ins/get-attachments-of-an-outlook-item | get attachments from the selected item}. + * * **Note**: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. * * [Api set: Mailbox 1.5] @@ -12316,21 +12328,24 @@ declare namespace Office { /** * Gets a string that contains a token used to get an attachment or item from an Exchange Server. * - * The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. + * The `getCallbackTokenAsync` method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. * The lifetime of the callback token is 5 minutes. * * The token is returned as a string in the `asyncResult.value` property. * - * You can pass the token and an attachment identifier or item identifier to a third-party system. - * The third-party system uses the token as a bearer authorization token to call the Exchange Web Services (EWS) GetAttachment or - * GetItem operation to return an attachment or item. For example, you can create a remote service to get attachments from the selected item. + * You can pass both the token and either an attachment identifier or item identifier to a third-party system. The third-party system uses + * the token as a bearer authorization token to call the Exchange Web Services (EWS) + * {@link https://docs.microsoft.com/exchange/client-developer/web-service-reference/getattachment-operation | GetAttachment} operation or + * {@link https://docs.microsoft.com/exchange/client-developer/web-service-reference/getitem-operation | GetItem} operation to return an + * attachment or item. For example, you can create a remote service to + * {@link https://docs.microsoft.com/outlook/add-ins/get-attachments-of-an-outlook-item | get attachments from the selected item}. * - * Your app must have the ReadItem permission specified in its manifest to call the getCallbackTokenAsync method in read mode. + * Calling the `getCallbackTokenAsync` method in read mode requires a minimum permission level of **ReadItem**. * - * In compose mode you must call the saveAsync method to get an item identifier to pass to the getCallbackTokenAsync method. - * Your app must have ReadWriteItem permissions to call the saveAsync method. + * Calling the `getCallbackTokenAsync` method in compose mode requires you to have saved the item. + * The `saveAsync` method requires a minimum permission level of **ReadWriteItem**. * - * [Api set: Mailbox 1.0] + * [Api set: Mailbox 1.0 for Read mode support; 1.3 for Compose mode support] * * @remarks *