WATCHDOX DOCUMENT CONTROL (WDP) API

Revision 1.2
Revision history

9/1/09 Created Yonatan

Introduction

This document outlines the usage and integration of the WatchDox document
protection API. This API is intended for partners wishing to integrate WatchDox
solutions in their sites or applications.

Using the WDP API, WatchDox partners may incorporate document tracking and
protection in applications, allowing partners to programmatically protect
documents, assign permissions to documents and users, and access the audit-trail
collected for documents .

In order to use the WatchDox API, prospective partners should contact WatchDox in
order to enroll into the WatchDox API partnership program. After Enrollment,
partner will receive a private identification token (enrollment token) used to
authenticate with the WatchDox servers. For more details, please contact
partners@confidela.com.

This document is organized as follows. The main facilities implemented in the API
are listed in section “Facilities”. In section “Use-Cases” we describe sample uses of
the API in order to perform common tasks such as document protection, permission
editing and user management. Last, API is detailed in the section “Detailed Function
Listing”.

Accessing the API

The API is accessed as a RESTful web service, i.e. operations on documents are
accessed by issuing HTTP(S)? commands to the WatchDox web-service url. The API
can be accessed by at https://api.watchdox.com/document/. The version of API is
supplied in the HTTP header.

Facilities
The WatchDox API is divided into several facilities. Each Facility is a collection of
related operations.

• User Management and Authentication

• Login

• Document Protect API

•
 • Document Management

• Partner Setup

User Management and Authentication

[This is not very clear. Is this for adding employees programmatically into the
system?]

This section may need to go to the end. It’s also not necessary in every case – for
example Symantec integrating into a DLP system. Our system should rely on the
DLP system to provide the document owner’s email+document+permissions. There
is no need to authenticate anything. We trust the integration into the DLP or into
any other partner system. So to sum up – this section is not required in many cases.

In order to use the WatchDox API, partners may want to associate an email address
with a password. This email and password pair is then used to authenticate with the
WatchDox service. A WatchDox partner may register an email address associated
with their domain by calling the Register User function. This function receives the
authentication token, the requested email and the requested password. Upon
completion, the new email and password can use the Login facility in order to
authenticate with the system.

The Register User API can only be used to register email addresses within a
partner’s domain. Partners wishing to register an email address outside their
domain must undergo an authentication process. Such a process is required, for
instance, if a partner wishes to integrate WatchDox onto a mail program running on
an unsupported mobile device.

The authentication mechanism is used by WatchDox to register a new user

associated with a specific email address. The authentication is based on our
innovative email-based authentication system. Calling the “Authenticate Email” API
triggers the system to send an email with a challenge string. Once received, the
“Register authenticated user” function uses to associate a password with the
registered email.

Usage Example:

1. Partner (x.com) calls “Register User” to associate “publisher@x.com” with

the password “secret” supplying the private identification token.

Login
The Login API is the mechanism used by partner application to identify a registered
user to the WatchDox system. It is performed by issuing a call to the “Login”
function with the username and password for a user (See User Management about
creating users to use with the WatchDox API). The “Login” function returns a
session identifier which is used in subsequent calls to other API functions.

In order to signal that a given session is ended and no more operations will follow,
the partner’s program should call the “Logout” function.

We probably need to think about a “generic” login of a system where there is no

specific user. Example: a DLP system. For each specific document it will upload
there may be a different document owner, there the system itself needs to “login”
but then with each document upload it needs to provide the document’s owner
email.

Usage Example:

1. Partner (x.com) calls “Login” with parameters “publisher@x.com” the

password “secret” and the identification token supplied during enrollment.
The function returns a SID number <SID>

Document Protect API

[I think this section should come first, it’s the most asked for]

Isn’t the first step to provide the document’s owner’s email? (only if it’s in the
scenario that a user is identified and the call is done from his/her machine this will
not be required) – think a DLP system… they find a document, identify the owner
and then want to upload it with some pre-defined policy they have.

This API is used to protect documents with the WatchDox service. Using the “Upload
Document” function, a partner’s application may upload a document to the
WatchDox service in order to perform the protection operation. Once uploaded, the
document is converted into the WatchDox proprietary secure format as well as
encrypted in its original format (to allow a download option). The upload process
returns a file identifier that can later be used to access this file, download its
protected version, track it and modify permissions.

Following, the partner’s application calls the “Submit Document Permissions”

function and sets the list of allowed recipients (This list of recipients may later be
edited by using the functions in the “” facility). Once the set of permissions is
defined, the document becomes available.

The “Get Document Info” function is used to retrieve document information.

Amongst the information fields are two URL fields that can be used to publish the
document: The URL where the document can be viewed online and the URL from
which a protected version can be downloaded (for supported formats only –we will
support PDF soon… so every file could be downloaded).

Last, a partner may wish to notify the authorized recipients that a document
became available by using the “Send Notification Email” API. This function will send
an email to a list of recipients (if permitted to the document) including a link to view
the document online (or download its protected version). The notification email
contains several customizable components. The body of the message is set for each
email and is taken as a parameter of the “Send Notification Email” function. In
addition, each email contains a logo, a textual header and textual footer. In order to
customize the logo, header and footer see the “Partner Setup” facility.

Usage Example:

1. Partner’s application calls Upload Document, using <SID>, SomeFile.Doc and

obtains an ID <File ID>

2. A subsequent call to “Submit Document Permissions” is made with <SID>,

<File ID> and “view only” to everybody in domain “x.com”

3. The partner’s application calls “Get Document Info” with <SID>, <File ID>
and retrieves the URL where the document can be viewed at
“www.watchdox.com/document/document_url

4. The application sends out an email with the link to the document to a certain
user (optional).

Document Permission Management

This facility is used to modify the protection (list of recipients and their rights) of
documents previously protected by WatchDox. A Partner’s application may call the
“Set Permission” function to set the permission on a given document. The update
takes effect immediately.

In order to obtain the list of permissions effective for a document, a partner may
use the “Get Permission” function.

In order to simplify common tasks such as adding a single recipient or revoking

permissions for a single recipient two convenience functions are available: The “Add
recipient function” is used to add permission while retaining the permission of all
existing recipients. The “Revoke Permission” function is used to remove the
permission of single recipient.

What about Edit existing permissions?

Usage Example:

1. Call to “Set permission” with <SID>, <File ID>, [{“alice@x.com”, “edit”},

{“x.com”, “view”}]. This will allow all recipients from “x.com” to view the
document, and allow alice@x.com to edit the document as well.
 2. Call to “Add recipients” with <SID>, <File ID>, “bob@y.com”, “view”. This
call will allow bob@y.com to view the document previously uploaded, while
retaining all permissions for alice@x.com and the entire x.com domain.

Document Management
The document management facility is used to obtain information on documents that
the user either owns or is permitted to view.

The facility includes the following operations

• List Documents in a folder - This operation lists the documents in a given

folder (if no folder is given, the root folder is used). The function returns a list
of Names and File Ids (for instance, usable in the “” facility) in the folder.

• List Folders - This operation lists the set of folders in a given folder (If no
source folder is given, the root folder is used)

• Update Document – This operation replaces the content of a file on the

WatchDox system without modifying its set of permissions. The existing
recipients of the document may use the same URL as before, but the content
they would receive would reflect the new file. Recipients who downloaded an
offline copy should download the file again. k

• Delete Documents (Completely remove a file from the WatchDox system)

Collect Audit Trail

This facility is used to obtain the list of operations performed on a document owned
by a user. Document owner may use any request the audit-trail for a given
document by issuing the “Get Audit Trail” function. This function requires a valid
<SID>, <File ID> and returns a list of operations. Each operation is an object
containing the operation type (View, Print, Download, Add Permission etc…), the
identity of the user who performed the operation, a supplemental identity (for
instance, document was forwarded to another email) and a textual representation
of the operation.

Usage Example:

1. Assume partner wishes to collect list of viewers for document represented by

<File ID>

a. Call “Get Audit Trail” with <SID>, <File ID>

b. Obtain a list of operations

c. Filter all operation that aren’t “View” operation.

 d. Return list of all identities that correspond to “View” operations.

Partner Setup

1. I don’t think I want an API here. This we would do for the partner or automate
via a portal. I don’t want to become a dynamic list server service. If they want
to customize each email they should send their own.

2. If this section stays here, I’d add info about CSS and subdomain support (not
required right now).

The Partner Setup facility is used to modify various parameters that affect the
configuration of the send process. The partner setup facility is used to customize
the logo and textual content of the emails sent by the system. The Partner Setup
facility requires that WatchDox API support enables the customization features. The
partner setup facility exposes the following operations.

• Set Notification Email– This operation is used to to set the logo (fixed-size
XXX 200x400 image), the header and the footer of notification emails sent
by the “Send Notification Email” function.
This function is called with the enrollment token, the logo image, and the
header and footer texts.

• Test Notification Email – This functions is used to test the logo, header and
footer before applying them with the “Set Notification Email” function. This
function gets the same parameters as the “Set Notification Email” and an
additional email, and sends a test email to the supplied address.

Adi: What a “secure viewer” API that is called and then streamed into an iFrame?
Can you write something about that? – not a priority. If we can just write one
paragraph about it fine, but it’s not a priority.

Use-Cases

Protecting a Document with WatchDox

Document Protection:

1. Invoke the login API with the user and password. Obtain a session identifier (SID)

2. Invoke the protection API. Supply the SID, File Name & Content and list of
recipients. This operations returns an identifier for the protected file
3. Invoke the protection API with the SID and file identifier. This operation returns
the URL accessible for the list of recipients supplied in step 2.

4. Repeat steps 2 and 3 for any additional files

5. Invoke the login API to logout and complete this session

[12:22:15 PM] Yonatan Amit: * Use-Cases and example: Full cycle integration: Sending a
document for a pre-registered owner.

[12:22:31 PM] Yonatan Amit: * Use-Case 2: Chaging permissions for an existing documents I
own

[12:22:49 PM] Yonatan Amit: * Use-Case 3: Getting the Audit-Trail for a document I own

[12:23:14 PM] Yonatan Amit: * Use-Case 4: Adding a new owner to my organization so I can
send documents that he owns

[12:28:00 PM] Yonatan Amit: replace the word "use-cases" above, let's add "Integrating with a
DLP system",[M.R.>] “integrating with my content generating or content management
application (e.g. engineering assets)”* and "Publishing a document on the web to allowed
users"

[12:29:40 PM] Yonatan Amit: ?VDR?[M.R.>] - the APIs should allow to build a desktop
application to upload documents to a VDR.

[12:36:04 PM] Yonatan Amit: Use-Case for Blackberry: Enroll an email address by using email
authentication mechanism

[12:37:07 PM] Yonatan Amit: Use-Case 1.5: Getting my list of documents and tracked
documents.

[12:37:32 PM] Yonatan Amit: list of documents I own, of course.

Detailed Function Listing