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 Permission Management

 Document Management

 Collect Audit Trail

 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 “
Document Permission Management” 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 “
 Document Permission Management” 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