Box Python Next Gen SDK: Watermarks

Image by pch.vector on Freepik

Watermarking serves as a deterrent to unauthorized sharing of content. When a file or folder is watermarked, the email (or ip address) and a time stamp of the user, are added to the preview of the content.

This way if a user decides to print or screenshot the content, the watermark will be visible.

You can follow along this workshop with complete code samples via this GitHub Repo. We are using the Box Platform Next Gen Python SDK.

Let’s get started.

Concepts

Box watermarking is not the traditional sense of adding a company logo or a draft watermark to a document. Instead, it is a way to add a unique identifier to a file or folder. This identifier is a combination of the user’s email address (or ip address), and a time stamp of when the file was previewed.

The watermark visibility is determined by the user’s permissions on the file, and also the type of access such as downloading or previewing.

For a complete list of the watermark visibility rules, please refer to the support note.

Watermarking can be turned on or off for individual documents or for folders, affecting all documents in them.

Watermarking files

Let’s start by creating a method to turn on the watermark for a file. Consider this method:

def add_watermark_to_file(client: Client, file_id: str) -> Watermark:
    """Watermark a file"""
    update_watermark = UpdateFileWatermarkWatermarkArg(
        UpdateFileWatermarkWatermarkArgImprintField.DEFAULT
    )
    return client.file_watermarks.update_file_watermark(
        file_id=file_id,
        watermark=update_watermark,
    )

def main():
    ...

    # add watermark to file
    watermark = add_watermark_to_file(client, DEMO_FILE)
    print(
        f"\nWatermark:"
        f"\n  - created  at: {watermark.watermark.created_at}"
        f"\n  - modified at: {watermark.watermark.modified_at}"
    )

Resulting in:

Watermark:
  - created  at: 2024-01-18T14:43:32-08:00
  - modified at: 2024-01-18T14:43:32-08:00

Now if you open your box.com account, navigate to, and preview the file you should see the watermark:

Watermarked file

Of course, as the owner of the file, you can edit, and download the file without the watermark.

Remove watermark

Let’s now create a method to remove the watermark from a file:

def remove_watermark_from_file(client: Client, file_id: str) -> Watermark:
    """Remove watermark from file"""
    return client.file_watermarks.delete_file_watermark(file_id=file_id)

def main():
    ...

    # remove watermark from file
    remove_watermark_from_file(client, DEMO_FILE)
    print("\nWatermark removed")    

Resulting in:

Watermark removed

If you preview the file again, you should see that the watermark is gone.

File with no watermark

Watermarking folders

Applying watermarks to individual files is a tedious task. Let’s now create a method to apply watermarks to all files in a folder:

def add_watermark_to_folder(client: Client, folder_id: str) -> Watermark:
    """Watermark a folder"""
    update_watermark = UpdateFileWatermarkWatermarkArg(
        UpdateFileWatermarkWatermarkArgImprintField.DEFAULT
    )
    return client.folder_watermarks.update_folder_watermark(
        folder_id=folder_id,
        watermark=update_watermark,
    )
    
def main():
    ...

    # add watermark to folder
    watermark = add_watermark_to_folder(client, DEMO_FOLDER)
    print(
        f"\nWatermark:"
        f"\n  - created  at: {watermark.watermark.created_at}"
        f"\n  - modified at: {watermark.watermark.modified_at}"
    )

Resulting in:

Watermark:
  - created  at: 2024-01-18T15:01:33-08:00
  - modified at: 2024-01-18T15:01:33-08:00

Once again if you preview the file you’ll see the watermark:

Watermarked file

Remove watermark from folder

Finally let’s create a method to remove the watermark from a folder:

def remove_watermark_from_folder(client: Client, folder_id: str) -> Watermark:
    """Remove watermark from folder"""
    return client.folder_watermarks.delete_folder_watermark(
        folder_id=folder_id
    )

def main():
    ...

    # remove watermark from folder
    remove_watermark_from_folder(client, DEMO_FOLDER)
    print("\nWatermark removed")

Resulting in:

Watermark removed

Now that we removed the watermark from the folder, if you preview the file again, you’ll see that the watermark is gone.

File without watermark

Final thoughts

Watermarking is way to deter users from sharing content, and must work in tandem with other security features.

Watermarking can also be automatically applied using security policies defined by administrators, such as Box Shield.

Getting started with Box Shield Smart Access

Documents and references

• API Watermark files
• API Watermark folders
• Support note

Thoughts? Comments? Feedback?

Drop us a line on our community forum.