Introducing the Box Watermarking API: Apply Watermark Overlays to Files and Folders

Today, we are excited to announce the Box Watermarking API that makes it easy to protect sensitive files in your apps. Using the Box Watermarking API, you can apply a semi-transparent overlay to a rendering of a file displayed in your app's user experience to indicate that a file contains sensitive or privileged information.

The watermark displays a current viewer’s email address or user ID (depending on the type of user account and whether or not the viewer is logged in), as well as the time of access over a file’s contents. Watermarks can be applied to files, including text-based documents, presentations, and images, as well as applied to folders where a watermark overlay would be applied to all the files contained in that folder.

Oftentimes, content applications facilitate sharing and collaboration around sensitive or privileged information, like sharing the latest product collateral with trusted partners and resellers. The Box Watermarking API allows you to easily protect sensitive content and deter any unauthorized sharing.

The Box Watermarking API is available to all Developer, Enterprise, and Elite Box Plans. To get started, you can create a Box Developer account for free or log in and create a new application in the Box Developer Console. If you have any questions about the Box Watermarking API, please visit our Developer Forum. You can also follow us on Twitter at @BoxPlatform.

How does the Box Watermarking API work?

Watermarking is represented as a sub-resource on the File and Folder resources in the Box Content API. You can think of the sub-resource as a “label” marking whether or not the file or folder is watermarked. If you apply this label, then the file will be protected by the watermark. The watermark will display on an embedded preview of that file, generated via the Get Embed Link endpoint of the Box Content API. If a developer allows a user to download a file, the watermark will also display on the downloaded version of the file.

The default watermark imprint for Box Managed Users accessing watermarked content is their login email address and the current timestamp. For anonymous users, it is their IP address and current timestamp. For App Users, it is their user id and current timestamp. The default watermark cannot be customized at this time.

The Box Watermarking API allows you to: get a watermark, apply a watermark, or remove a watermark on a file or folder in Box. To use the Box Watermarking API, you'll need the file or folder ID.

Applying a Watermark to a File

To apply a watermark to a file, you would make the following API call:

curl https://api.box.com/2.0/files/5010739069/watermark \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"watermark": {"imprint": "default"}}' \
-X PUT

The Box Content API would respond with the created_at and modified_at timestamps for the watermark. If the file did not previously have a watermark applied to it, 201 Created is returned. Otherwise, 200 OK is returned. Both responses contain the following JSON:

{
"watermark": {
"created_at": "2016-10-31T15:33:33-07:00",
"modified_at": "2016-10-31T15:33:33-07:00"
}
}

Next, you’d need to request an expiring URL for creating an embedded preview session that will display the file in your app. To do this, you’d perform a GET request to obtain the link that you can then embed in an iframe.

curl https://api.box.com/2.0/files/5010739069?fields=expiring_embed_link \
-H "Authorization: Bearer ACCESS_TOKEN"

This call would return a response with the “expiring_embed_link” URL.

{
"type": "file",
"id": "5010739069",
"etag": "1",
"expiring_embed_link": {
"url": "https://app.box.com/preview/expiring_embed/gvoct6FE!Qz2rDeyxCiHsYpvlnR7JJ0SCfFM2M4YiX9cIwrSo4LOYQgxyP3rzoYuMmXg96mTAidqjPuRH7HFXMWgXEEm5LTi1EDlfBocS-iRfHpc5ZeYrAZpA5B8C0Obzkr4bUoF6wGq8BZ1noN_txyZUU1nLDNuL_u0rsImWhPAZlvgt7662F9lZSQ8nw6zKaRWGyqmj06PnxewCx0EQD3padm6VYkfHE2N20gb5rw1D0a7aaRJZzEijb2ICLItqfMlZ5vBe7zGdEn3agDzZP7JlID3FYdPTITsegB10gKLgSp_AJJ9QAfDv8mzi0bGv1ZmAU1FoVLpGC0XI0UKy3N795rZBtjLlTNcuxapbHkUCoKcgdfmHEn5NRQ3tmw7hiBfnX8o-Au34ttW9ntPspdAQHL6xPzQC4OutWZDozsA5P9sGlI-sC3VC2-WXsbXSedemubVd5vWzpVZtKRlb0gpuXsnDPXnMxSH7_jT4KSLhC8b5kEMPNo33FjEJl5pwS_o_6K0awUdRpEQIxM9CC3pBUZK5ooAc5X5zxo_2FBr1xq1p_kSbt4TVnNeohiLIu38TQysSb7CMR7JRhDDZhMMwAUc0wdSszELgL053lJlPeoiaLA49rAGP_B3BVuwFAFEl696w7UMx5NKu1mA0IOn9pDebzbhTl5HuUvBAHROc1Ocjb28Svyotik1IkPIw_1R33ZyAMvEFyzIygqBj8WedQeSK38iXvF2UXvkAf9kevOdnpwsKYiJtcxeJhFm7LUVKDTufuzuGRw-T7cPtbg.."
}
}