Box Sign is an e-sign product that is available for Box customers to create, send, and complete documents that need a signature from one or many parties. While Box provides a robust set of tools from within our first party web application to manage these requests, as a partner, you may want to bring the sign management and capabilities into your application, so that a mutual customer would be able to review and send these requests without leaving your product.
Integrating with Box Sign
The process of integrating with Box Sign is quick as we provide a few different endpoints for Sign—getting information about all or specific existing Sign requests, creating new Sign requests, and resending or cancelling existing requests. If you are new to integrating with Box, go through the steps of registering for a developer account and creating your first application in our section on Integrating with Box. This guide will go into more specific scopes and permissions needed and requires the basic steps to be completed.
Choosing the Authentication Type
When creating an application, you are given the choice between utilizing 3-legged OAuth or JWT based OAuth for your authentication type. In general, these types are similar and we recommend choosing based on what is best for your application. Note that you are likely going to be performing actions on behalf of individual users in Box, so depending on your choice, you need to make sure you’re checking the correct scopes within your application.
Application Permissions
JWT Authentication
-
If you are using a JWT based authentication mechanism, you will need to make sure that your application is set up with the following settings:
-
App Access Level: App + Enterprise Access. As you will be performing actions such as downloading content and adding classifications on behalf of enterprise users, you will need to be able to access the named users in the enterprise.
-
Application Scopes: these are the minimum permissions required to be able to get user information, download files, apply classifications, and utilize the Enterprise Event stream to capture user actions.
-
Read all files and folders stored in Box
-
Write all files and folders stored in Box
-
Manage Signature Requests
-
Manage Users
-
Advanced Features
-
Issuing the API Call: select either, “Making API calls using the as-user header” or, “Generate user access tokens.” As Box checks permissions based on the user issuing the API call, you will need to impersonate a Box user when downloading content. These settings are the two ways to accomplish this requirement.
OAuth 2.0 Authentication
-
For OAuth 2.0 based authentication you will need to have the following settings:
-
Application Scopes: these are the minimum permissions required to be able to get user information, impersonate individual users and send Signature Requests.
-
Read all files and folders stored in Box
-
Write all files and folders stored in Box
-
Manage Signature Requests
-
Manage Users
-
Advanced Features
-
Making API calls using the as-user header
User Permissions
There are no specific user permissions that would be needed for this flow, but you may need to make sure that Sign functionality is enabled in the enterprise itself. There is a Box Community guide on making sure that your enterprise is set up with Sign capabilities here.
Using the Box Sign API
When you are starting to work with the Box Sign API, it’s helpful to familiarize yourself with the object model of Box Sign which can be found here. There are a number of values such as validity time, reminders, and preparation urls that are specific to Sign.
As a first step, your application will need to connect to the customer Box environment. This is dependent on the authentication type that you selected for your application—in case of JWT, the main admin of the enterprise would need to add your application or you would need to have the user go through the OAuth flow to get the tokens.
Note that as Sign does not require admin permissions, you may authenticate either individual users of the enterprise directly and store a set of tokens for API calls for each one, or you may authenticate the admin of the enterprise, and then utilize the As-User header or User Token directly.
Once you are connected to a user, you can choose to see what Sign requests the user may already have as well as the status of the requests. You can also build in functionality into your integration to manage these requests by resending or cancelling them if needed. This way a user can have a full view into their requests without having to leave your integration.
One of the most powerful tools you can build directly into your integration is the ability to create and send Sign requests directly with a simple API call. There is a lot of customization that you can utilize when creating these requests directly within your user interface to allow end users to customize the signature request behavior.
For instance, an important customization during this flow is the, “is_document_preparation_needed” boolean as this allows the user to be sent a URL where they can actually prepare the selected document by adding in Signature blocks and tags before sending it to the final recipients. You can read more about document preparation on our developer site here. It’s also worth noting that a document will go through many different status codes during it’s lifecycle which can be found here.
With these API endpoints you can bring the Box Sign functionality directly into your application and simplify the management of requests for our mutual customers.