Box Developer Platform

Getting Started with the New Box View

Overview

Box View allows a-la-carte access to Box's Preview services for 120+ Content Types (including documents, images, HD videos, 360 images, 360 videos, 3D models - full list here) independent of the underlying user, permissions and collaboration model.

Using a new authentication mechanism in Box called App Token Authentication or "Auth" for brevity, developers can now preview any application-owned content through Box Preview, without having to tie the content to a user in Box (Anonymous Access). This essentially provides application developers a way to use Box's Preview services for use cases that do not require other components of Box Platform (user models, file/folder structure, permissions, etc.)

To generate a Preview Embed Link using App Token Authentication, follow these steps:

  1. Create a new Box View application through the Developer Console
  2. Generate an App Token through the Developer Console
  3. Upload a document using the App Token and Upload API
  4. Retrieve a File Token using Token Exchange (optional)*
  5. Generate a Preview using the App/File Token/Annotator Token (to enable annotations) and Get Embed Link API

**recommended if you are using the Box Javascript Preview SDK, or if you are generating the expiring embed on the client side.

Accessing App Token Auth through the new Box Developer Console

App Token Auth is currently available via the new Box developer console only. To start building using App Token Auth, follow these steps:

Endpoints supported via App Token Auth

App Token Auth currently only supports previewing content stored in Box. The only Content APIs accessible through App Token Auth are Upload File, Download File, Delete File and Get Embed Link.

To provide feedback, please contact us at new-box-view@box.com. We would love to hear from you!

Create a New App Token Auth Application through the Developer Console

In the new Box Developer Console, click on "Create New App" under "My Apps"

Next, select "Custom App" from the options and click Next.

Now, select "App Token (Server Authentication)" and click Next.

Give your app a name, and click "Create App".

Fantastic! You just created your first App Token Application.

Generate an App Token through the Developer Console

The configuration page for your application should look like this:

Before moving on, here is some more important information on App Tokens.

App Tokens are a set of two tokens (primary and secondary) that hold elevated privileges over the content managed by your application. They are essentially your application's gateway to using Box View services. App Tokens can be used by your application to upload, download, preview and modify any content into Box. Due to the elevated privileges granted to the application tokens, if you need to make the token available on the client side for any reason (eg: if you are using the Preview SDK instead of the Expiring Embed or generating the Expiring Embed from the client-side), we strongly recommend that you don’t use App Tokens to generate preview links as you don't want anyone sniffing the App Token from the client device. Use File Tokens for this instead.

That said, if you are generating the Expiring Embed on the server side, you can safely continue to use the App Token itself.

Due to the elevated permissions granted to App Tokens, we have taken the following steps to ensure security of these tokens:

  1. Box doesn’t store the App Tokens, but instead stores a hash of them. Therefore, once your token is generated, please make sure to copy it and store it securely since it won’t be displayed upon page reload.
  2. Box requires that you setup 2FA on your developer account before you can revoke/generate App Tokens.

To begin, click "Create a Primary Access Token".

**If you don't have 2FA setup for your developer account, you will be prompted to setup 2FA before you can successfully generate App Tokens. Follow the prompt to setup 2FA and once done, return to this page and try again.

Next, choose an expiry for your token and click “OK”.

**If you choose “No Expiry”, the application token will not expire until you manually revoke it. App Tokens can be revoked anytime through the Developer Console.

Copy the App Tokens and store it securely. It won’t be displayed once the page is reloaded since Box stores a one-way hash of these tokens, and thus cannot retrieve the original token again.

Upload a Document using the App Token and Box Upload API

To generate a Preview Embed Link, the content first needs to be uploaded and converted in Box. Conversion is triggered automatically upon upload (for most document types) or on first preview (for video and 3D) and no explicit action is required by the user to convert once the file is uploaded. In either case, conversion is triggered only once per file, and the generated assets are available for as long as the original file is present in Box.

To upload the document into Box, use Box's Upload File API. Use folder id “0”.

A 201 response indicates that the file has been uploaded successfully. The response body contains the “file id” of the uploaded file, which we will use in the next step when generating the File Token for this file.

Note: We recommend that you keep the content in Box for as long as your application will use it to generate a preview. Content can be deleted from Box later using the Delete File API. However, please bear in mind that every upload to Box counts towards your conversion quota. That said, you have the option to delete the document later using the Delete File API if you choose to do so.

Retrieve a File Token using Token Exchange (Optional)

If you plan on generating a preview link using the Preview Embed Link from the application server (and not client), you can skip this section and use your App Token directly to generate the embed link

If for some reason you need to generate a preview link from the client, or you are using the Preview Javascript SDK, you risk exposing the token to the user. For this reason, you should not send the App Token to the client device. You can use a File Token for this instead. Unlike an App Token which can be used to access all the content in the application's content repository, a File Token is a lower privilege token that is generated only with preview permissions to the specific file that you wish to preview.

The App Token can be "exchanged" for a lower-scoped File Token by the application server by making a token exchange request as shown below. The App Token remains unaffected by the token exchange request.

A File Token is valid up to 60 minutes from the time it is generated.

Request

POST /oauth2/token HTTP/1.1

Request Body

{
    "subject_token":"<YOUR-PRIMARY-OR-SECONDARY-APP-TOKEN>", 
    "subject_token_type" :"urn:ietf:params:oauth:token-type:access_token", 
    "scope":"item_preview", 
    "resource" : “https://api.box.com/2.0/files/{file_id}”,
    “grant_type” : “urn:ietf:params:oauth:grant-type:token-exchange”
}
Input Paramters
Description
Required?

subject_token

string

This is the primary/secondary application token you will exchange for the file token.

Yes

subject_token_type

string

The subject token type is “urn:ietf:params:oauth:token-type:access_token”

Yes

scope

string

Scope granted to the exchanged token. Please see the table below for the possible values for this parameter.

Yes

resource

string

Full url path to the file that the token should be generated for, eg: “https://api.box.com/2.0/files/{file_id}”

Yes

grant_type

string

Grant type being used –
“urn:ietf:params:oauth:grant-type:token-exchange”

Yes

Scope Names
Description

item_preview

Preview content. Create and edit annotations and comments.

item_content_upload

Upload to a specific file or folder.

item_delete

Delete a specific file or folder.

Successful Response

The response contains the File Token under "access_token". We will use this to generate the Preview Embed Link in the next step.

{
	"access_token": "1!R7IC45MCAJscOKiA3bb…”,
  "expires_in": 3867,
 	"token_type": "bearer",
	"restricted_to": 
	[
    	{
      		"scope": "item_preview",
      		"object": 
					{
        			"type": "file",
        			"id": "5025021389",
        			"file_version": 
							{
          				"type": "file_version",
          				"id": "141545073",
          				"sha1": "3a29fe699…"
        			},
        			"sequence_id": "0",
        			"etag": "0",
        			"sha1": "3a29fe69…",
        			"name": "your file"
      		}
    	}
  ],
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

Error Codes

HTTP Status Code
Error Code
Description

400 Bad Request

invalid_request

The request is missing a required parameter or includes an unsupported parameter value. This is set if the principal does not have view permissions on resource, if the id is malformed or the subject_token is invalid or expired.

400 Bad Request

invalid_resource

The “resource” specified in the request is either malformed, has an invalid id or is not viewable using the subject_token.

400 Bad Request

invalid_scope

The requested scope is invalid.

Generate a Preview using the File Token and Get Embed Link API

To Preview the document you must generate an Preview Embed Link for the document. To do this, use the Box's Get Embed Link API. Use the App or File Token generated in the previous step as the bearer access token.

For security reasons, the generated embed link will expire after 1 minute and should be embedded immediately in the app once generated.

Best Practices To Rollover Your Application Token

The App Token is a highly privileged token. To keep your application functional, you may want to rollover your App Token if it is about to expire. If you are using non-expiring tokens, you may still want to rollover your App Token if it gets compromised.

We have provided you with a Secondary App Token that works exactly the same as the Primary App Token and can be used to rollover your App Token without incurring any application downtime.

We suggest the following workflow for rolling over your Primary App Token:

  1. Generate the Secondary App Token through the Developer Console UI.
  2. Replace the Secondary App Token in your application and roll out the change.
  3. Once your application starts using the secondary App Token, revoke the Primary App Token.

Using the Preview SDK to Customize the Preview Experience in Your Application

The Get Embed Link endpoint is a light-weight API endpoint that provides limited options to customize the preview experience in your application. Due to the light-weight nature of the endpoint, the API doesn't give you options to respond to client-side actions such as scrolling in the case of documents, play/pause interactivity for videos, rotating an image, etc.

To leverage advanced capabilities such as those listed above and control the preview experience in your application at a fine-grained level, please use the Box Preview SDK.

To learn more about the Preview SDK and and for further documentation on how to use it, please go to our page on the Box Javascript Preview SDK.

Annotations

Annotations is now available for new Box View!

Annotations is one of the key features supported by new Box View, that allows developers to provide collaboration capabilities right from within the embedded Box preview in their application. Annotations fits a wide range of use cases and can be used to draw the reader's attention and/or provide feedback on specific parts of a document or images.

Box View supports three annotation types today - highlight only, highlight annotation and point annotation (works especially well if you need to annotate images). Annotations are today supported on documents and image previews only (see here for all file types and extensions supported by Box).

How Annotations works with New Box View

Since new Box View is designed keeping in mind applications that don't create and manage individual user-level accounts in Box, we have built annotations in a way that it enables these applications to use annotations without creating and managing individual user accounts in Box.

The way this works at a high-level (detailed instructions below) is that the application server can generate an "annotator token" and use that instead of an app/file token to generate the preview session (expiring embed link). An annotator token is essentially a file token with external user details (UniqueId and DisplayName) embedded in it. UniqueId and DisplayName are arbitrary fields from Box's perspective and are intended to be supplied and managed by the application. Box Annotations just uses these for the purpose of attributing the annotations to the external user whose details are embedded in the annotator token.

NOTE: Since a preview session generated using an annotator token is tied to a specific external user, it is strongly recommended that your application generates different preview sessions (using different annotator tokens) for different end users of your application.

The diagram below shows the series of calls to generate an annotator-specific preview session. In the sections below, we will go into the details on how to generate an annotator token.

Annotations External Display Name

The external display name associated with an annotation is essentially a stateless "label" appended to the annotation. This means that once an annotation has been added, the display name is permanently associated with the annotation and cannot be updated (unless the annotation is deleted and added again with the updated display name).

Currently, there is no way for applications to update the external display names for existing annotations once they have already been made. Please email us at new-box-view@box.com and let us know if this is a core requirement for your use case.

Generating an Annotator Token

There are two steps to generating an Annotator Token:

  1. Create an actor token (using JWT) that encapsulates the external user information
  2. Generate an annotator token using the actor token and app token

Create an actor token (using JWT) that encapsulates the external user information

Actor Token is a JWT Assertion that encapsulates the annotator token. This JWT assertion is composed of three components, the header, claims and signature. The signature, in this case, is an empty string.

To construct the JWT assertion, the two components must be base64 encoded and concatenated using a “.” separator:

<base64URLencoded header>.<base64URLencoded claims>.<base64encoded signature>

Once encoded and concatenated, the JWT assertion will look like this (note, the signature, after the second "." is empty)

eyJhbGciOiJub25lIn0K.eyJpc3MiOiJsZm9jbTE0ZmM5c3BtaGVyczRlajNkeXFjZXp0cjRqYSIsInN1YiI6IjEyMzQiLCJib3hfc3ViX3R5cGUiOiJleHRlcm5hbCIsImF1ZCI6Imh0dHBzOi8vYXBpLmJveC5jb20vb2F1dGgyL3Rva2VuIiwiZXhwIjoxNDc4MjkzNzMwLCJqdGkiOiI4OXVpaGtqZGJmYXNjdGhlMTkxNDc4MjkzNzMwIiwibmFtZSI6IklkZW50aXR5IERlbW8ifQo=.

JWT Libraries

Fortunately, there are many libraries available for easily constructing the JWT assertion. These can be found here.

Constructing the Header

Header Attributes

Parameter
Type
Description

alg

required

String

The algorithm used to verify the signature. Only value supported is "none".

typ

required

String

Type of token. Default is “JWT” to specify a JSON Web Token (JWT).

Example Header

{
    "alg": "none",
    "typ": "JWT"
}

Constructing the Claims

Claims Attributes

Parameter
Type
Description

iss

required

String

The API Key of the application that is creating the JWT assertion.

sub

required

String

External Unique Id of the annotator.

aud

required

String

jti

required

String

Unique JWT Identifier that is at least 16 characters and at most 128 characters.

exp

required

String

Limits the window during which the JWT can be used. Should be set to a maximum value of 60 seconds after the issue time.

box_sub_type

required

String

Box private claim. Set to the value “external”.

name

required

String

Display name of the annotator

iat

optional

NumericDate

Issued at time. The token cannot be used before this time.

nbf

optional

NumericDate

Not before. Specifies when the token will start being valid.

Based on the above parameters, we can construct an example set of JWT claims:

{
    "iss": "<API-KEY>",
    "sub": "<EXTERNAL-USER-ID>",
    "box_sub_type": "external",
    "aud": "https://api.box.com/oauth2/token",
    "jti": "M4yeY3W63TxHa9jFek85",
    "exp": 1428699385,
    "name":"<EXTERNAL-DISPLAY-NAME>"
}

External ID restricted to 48 characters

The "sub" field which is meant to represent the Annotator's external user id is restricted to a maximum of 48 characters. A longer id will result in your "Create Annotation" call failing. If the user id in your application database is longer than 48 characters, we recommend truncating it or creating a separate (and shorter) unique ID that can be used with Box.

The base64 encoded versions of the "header" and "claims" appended together will give you the actor token.

Generate an annotator token using the actor token and app token

This step is almost identical to generating a File Token above, with the only difference that there are two additional fields included in the request - "actor_token" and "actor_token_type". The "actor_token" parameter will contain the JWT assertion that you constructed above, while "actor_token_type" is set to urn:ietf:params:oauth:token-type:id_token. Full list of query params for generating an annotator token can be found below.

Just like a File Token, an Annotator Token is valid up to 60 minutes from the time it is generated.

Request

POST /oauth2/token HTTP/1.1

Request Body

{
    "subject_token":"<YOUR-PRIMARY-OR-SECONDARY-APP-TOKEN>", 
    "subject_token_type" :"urn:ietf:params:oauth:token-type:access_token", 
    "scope":"item_preview", 
    "resource" : “https://api.box.com/2.0/files/{file_id}”,
    “grant_type” : “urn:ietf:params:oauth:grant-type:token-exchange”,
    "actor_token" : "<JWT-ASSERTION-FOR-ACTOR-TOKEN>",
    "actor_token_type" : "urn:ietf:params:oauth:token-type:id_token"
}

Same as that for File Tokens with the additional two fields below.

Input Parameters
Description
Required?

actor_token

String

This is the constructed JWT Assertion for Actor Token.

Yes

actor_token_type

String

Always set to "urn:ietf:params:oauth:token-type:id_token"

Yes

Successful Response and Error Codes

These are identical to those for a File Token.

Generating a Preview using an Annotator Token

To Preview the document you must generate an Preview Embed Link for the document. To do this, use the Box's Get Embed Link API. Use the Annotator Token generated in the previous step as the bearer access token.

For security reasons, the generated embed link will expire after 1 minute and should be embedded immediately in the app once generated.

NOTE: Before embedding the resulting embed URL link in your application, make sure to append "showAnnotations=true" to the end of the embed URL link to enable the Annotations UI.

Feedback

You can reach us new-box-view@box.com if you would like to provide any feedback on the product or documentation or if you would like to see additional Box services exposed through the App Token Authentication! Also, feel free to shoot us an email if you would like to share how you are using/planning to use Box View in your application.

Getting Started with the New Box View