From a26d6003ed0abca29afa8e8ce6a8218314cead04 Mon Sep 17 00:00:00 2001 From: Jeremy Press Date: Fri, 7 Jul 2017 14:37:46 -0700 Subject: [PATCH] Chore: Update README to include token scope information (#203) --- README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/README.md b/README.md index 534ff4e4f..2227c7411 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,34 @@ Access Token ------------ Box Content Preview needs an access token to make Box API calls. You can either get an access token from the token endpoint (https://docs.box.com/reference#token) or generate a developer token on your application management page (https://blog.box.com/blog/introducing-developer-tokens/). +If your application requires the end user to only be able to access a subset of the Content Preview functionality, you can use [Token Exchange](https://developer.box.com/reference#token-exchange) to appropriately downscope your App/Managed or Service Account token to a resulting token that has the desired set of permissions, and can thus, be securely passed to the end user client initializing the Content Preview. + +Below are a set of new UI Element-specific scopes to go alongside Token Exchange. These allow developers to enable/disable UI controls on the Content Preview by configuring the appropriate scopes on the downscoped token. To learn more, see [Special Scopes for Box UI Elements](https://developer.box.com/v2.0/docs/special-scopes-for-box-ui-elements). + +Wish to learn more about when, why and how you can use Token Exchange with the Content Preview? See our [blueprint on Customizing Access for the Box UI Elements](https://developer.box.com/v2.0/docs/customizing-access-for-ui-elements). + +### Base Scope + +| Scope Name | What permissions does it grant? | +| --- | --- | +| base_preview | Allows preview access to a file or files in a folder based on user/file/token permissions | + +### Feature Scopes +| Scope Name | What permissions does it grant? | +| --- | --- | +| item_download | Allows files/folders contents to be downloaded | +| annotation_view_self | Allows user to view their own annotations | +| annotation_view_all | Allows user to view all annotations on the file | +| annotation_edit | Allows user to edit their own annotations (includes annotation_view_self) | + +### Sample Scenarios + +| Scenario| Scope Combinations | +| --- | --- | +| User wants basic preview functionality + download | base_preview + item_download | +| User wants basic preview functionality + ability to edit own annotations| base_preview + annotation_edit | +| User wants basic preview functionality + ability to view all annotations + ability to edit own annotations| base_preview + annotation_view_all + annotation_edit| + Viewers ------- The name of a viewer can be one of the following `Document`, `Presentation`, `MP3`, `MP4`, `Dash`, `Image`, `Text`, `SWF`, `Image360`, `Video360`, `Model3d`, `CSV`, `Markdown`. Call `preview.getViewers()` to get the list of possible viewers.