Pre-requisites for Zoom APIs

Zoom exposes a rich set of APIs both in the form of command-line client or as JSON-based Web APIs. Before venturing into these APIs, there are a few basics that one would have to understand. This post covers the basic key parameters that are part of the Zoom APIs and some common initialization and connection mechanisms.

Entity Definitions

Through out the API documentation you will see several identifiers being referred to. Below is a definition of the commonly used entity identifiers by our APIs:

Entity Code Entity nameTypeDescription
fuidFile Unique IdIntegerUnique integer assigned to each asset independent of its name
bidBranch IdIntegerUnique integer assigned to a branch. Reserved for future use.
repoIdRepository IdStringUnique string assigned to a Zoom repository.
pidPath IdIntegerUnique integer assigned to each element of a file or folder path
rrnRepository revision numberLongUnique long assigned to each write transaction in the Zoom server.  Often used to refer to an asset change set.
frnAsset Revision NumberLongFile or Folder Version Number is a monotonically increasing number
projectProject NameStringA project within a repository is a collection of assets, security ACLs, users & roles.
projectRoot Project Root FolderStringThe parent folder of a project.
taskIdWorkflow task IdIntegerUnique integer assigned to a task in a specific workflow
workIdWorkflow Job IdIntegerUnique integer assigned to each job instantiated within the Zoom Workflow system

The most common entity identifiers that you will typically deal with are the tuple<fuid,bid>.  This tuple uniquely identifies an asset in the Zoom repository. Even if the asset is renamed or moved, the tuple stays the same, allowing you to track the version history of an asset.

Zoom Authentication & Authorization

Connecting to the Zoom Server

Zoom server on a successful authentication with the client, stores a cookie either on a hidden folder on the user’s home directory or in-memory. Depending upon the option, the cookie can be persistent (stored on disk) or transient (in-memory). After a command completes the transient cookie stored in-memory is wiped out.  If you intend to execute multiple commands use a persistent cookie. However if you are running commands in script on behalf of a user, you might want to use a transient cookie to avoid resetting any ongoing session of another user who may also be logged in on the same machine.

Persistent Session

By default Zoom creates a persistent session on authentication.  To authenticate using the command line, specify the user name & password on the command line to silently login. If the credentials are invalid the command will return an error and a non-zero process status:

zm –username <uid>  –password <pass>  <zoom-command>

For example –

zm –username joe –password joe getcredentials
zm –username joe –password joe version –all

Authentication using the Java API

Using the dialog launcher API, the Zoom Java based login form will automatically popup to authenticate the user. No additional code is needed for e.g.:

ProcessLauncher.launchDialog(ScreensEnum.IMPORT, server, project,                                                        branch, remoteDestFolder, localFilesToImport);

For a more low-level API, you can use the methods in the class com.zoom.admin.client.ProjectOptions to set the user name and password prior to invoking the low-level command APIs:

ProjectOptions po = com.zoom.admin.client.ProjectOption.getInstance();
po. setUsername(“joe”);
po. setPassword(“joe”);

// Invoke the check-in command directly without any GUI

CommitCommand c = new CommitCommand(app,nonrecursive,depth,

Transient Session

(Will be updated shortly)

Connect to Zoom Admin Server

Zoom supports sending JSON requests via AJAX to the following URL on the Zoom Admin Server:


wbm_server|port refer to the Zoom MAM Server (webmin) host name and TCP port (defaults to 8443).

In order for the webmin server to authenticate & authorize the user the following parameters must be passed via the URL query parameters or in the body of the Http POST requests:


For example –

POST /internal?zm_username=rahul&zm_cookie=21-750c34331b591bffee5ee7a2d5759f0d93bb157b

The user-name and cookie can be obtained by pulling the information using the “zm getcredentials” scriptable command or using the Java class GetcredentialsCommand.

The output of “zm getcredentials” command looks like this:

[joe@green ~]$zm –username joe –password joe -s http://localhost:8880 getcredentials
zm_repo_id: zoom-server-fe706ca57180507d76d3d98c3e1223340f50b314
zm_cookie: 2-01b027d78a2e3c099eff14fdf83fba166d6d5efa
zm_username: joe

We can obtain URL from “wbm_server” and the cookie from “zm_cookie”. The Zoom server performs the authorization based on the roles associated with the user’s credentials.

Connecting to Zoom Preview Server

Use HTTP POST to submit login credentials to the Preview Server login URL. After a successful authentication, Preview Server will set a session cookie (name: JSESSIONID) that needs to be sent with subsequent http request to the Preview Server. In addition a JSON response will be returned to indicate if authentication succeeded.

POST url:


Form Data to POST:


On success expect to receive the following:


Now you are ready to use the Preview Server API.

Get Credentials

As mentioned earlier the “zm getcredentials” can fetch the current logged in user’s credentials including the persistent cookie set by the Zoom authentication module.

Authentication Token

The “zm_cookie”  can be passed to any Zoom command or the Webmin APIs to authenticate a user. The cookie is stored in an authentication database on the user’s “.zm” folder under the home directory.

Leave a Comment