Supported operations

Zoho Vault APIs support a wide range of operations, as mentioned below. In future updates, you can expect support for other operations available in our web interface as well.

User Management

Invite a user
Retrieve user list
Retrieve user group details
Update user access
Update user role
Delete user

Password Management

Add a new password
View existing passwords
Edit password
Delete password
User details associated with password
Share passwords with users
Bulk share passwords with users and user groups
Share password with third-parties
Enforce access control for passwords

Folder Management

Add a new folder
View folders
Update the folders
Update sharing details for folders
Delete a folder

Implementation guide

Accessing Zoho Vault’s API requires authentication. You can use either an existing account in Zoho Vault or create a separate account for API.

There are two major methods for retrieving data from most web services: XML or JSON. However, for now, we only support the JSON method for retrieving data from Zoho Vault, as JSON has a comparatively standard syntax, compared to XML.

Step 1 - Using OAuth:

Web Server applications can implement OAuth 2.0 Authorization by hitting Zoho’s OAuth endpoints to access Zoho’s APIs. A short-lived authorization code is generated by Zoho accounts and sent to the third-party application via the user-agent (usually a web browser). An authorization code can be exchanged for an access token at Zoho Accounts. Users can also pass an additional parameter offline_access = true to generate refresh_token, which can be used to generate an additional access_token. For more details, you can check out this link.

Step 2 - Accessing Zoho Vault with OAuth & identifying the type of user account:

From your application in which you require read access to Zoho Vault passwords, call the GET_LOGIN API with the URI.

Zoho Vault uses two methods to derive and validate user’s master password based on user account. * Key derivation algorithm * Hashing Algorithm

NOTE:

Depending on the time of account creation, the algorithm may vary as “PBKDF2_AES” or “SHA256”.

Step 2 - Example

CopiedHTTP/1.1 2xx
Content-Type:application/json;charset=UTF-8

{
  "operation": {
    "result": {
      "message": "",
      "status": "success"
    },
    "name": "GET_LOGIN",
    "details": {
      "PASSPHRASE": "XxXXxxxxxXX/XXXxXxXXXXXXxXxxXXXxXX/xxXXxXXxXxxXxxx/xxXxXxX==",
      "SALT": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "ITERATION": 1000,
      "LOGIN": "PBKDF2_AES" OR "SHA256",
      "LASTMODFIEDTIME": "xxxxxxxxxxxxx",
      "USER": {
        "USERID": "xxxxxxxxxxxxx",
        "USERNAME": "API_User",
        "EMAIL": "API_User@domain.com"
      }
    }
  }
}

URI - https://vault.zoho.com/api/json/login?OPERATION_NAME=GET_LOGIN

Code Snippet to derive Master Key:

Copiedvar masterKey = null;
var passphrase = "user_master_password"; 
if(LOGINTYPE == "PBKDF2_AES"){
    var masterKey = Vault.PBKDF2_key(passphrase, SALT, ITERATION); 
}else{
    var masterKey = Vault.hash(passphrase);
    var passAuth = Vault.hash(passphrase+SALT); 
}

Step 3 - Fetching user’s data by calling the OPEN_VAULT API :

Next, call the OPEN_VAULT API to access the passwords, under the user account with the URI found in the right. https://vault.zoho.com/api/json/login?OPERATION_NAME=OPEN_VAULT&passAuth= where is the value derived from the code snippet mentioned in Step 2. If you would like to retrieve only specific amount of passwords, you can pass the parameter startIndex and limit along with the API URI. Additional parameters are required only if the hashing algorithm is SHA256.

Step 3 - Sample JSON response from the Zoho Vault server:

CopiedHTTP/1.1 2xx
Content-Type:application/json;charset=UTF-8

{
  "operation": {
    "result": {
      "message": "",
      "status": "success"
    },
    "name": "OPEN_VAULT",
    "details": {
      "OFFLINE_ACCESS": "Enabled",
      "PLANID": 8016,
      "POLICY_USAGE": "1",
      "SECRETTYPECOLUMNS": {},
      "SECRETS": [],
      "ALLOW_SHARING_SECRETS": "Enabled",
      "SHARINGKEY": "xxxxxxxxxxxxxxxxxxxxx",
      "PRIVATEKEY": "xxxxxxxxxxxxxxxxxxxxxx",
      "PERSONAL_SECRETS": "Enabled",
      "USER": {
        "USERID": "xxxxxxxxxxxxx",
        "USERNAME": "API_User",
        "EMAIL": "API_User@domain.com"
      },
      "ALLOW_ADD_SECRETS": "Enabled"
    }
  }
}

Here, "SECRETS":[ ], will contain the array of Secrets present under the account.


URI - https://vault.zoho.com/api/json/login?OPERATION_NAME=OPEN_VAULT&passAuth=<passAuth>&startIndex = &limit=.

Step 4 - Org key derivation:

All enterprise passwords are encrypted in Zoho Vault using a key called ‘Org key’. Please use the javascript on your right to derive the org key from the Zoho Vault server’s JSON response.

NOTE:

Null value will be returned for the variable userOrgSharedKey if the user’s sharing handshake process is not completed properly, i.e. the sharing status of the user in the Admin >> User management section should always be “Approved”.

Step 4 - Javascript code snippet to derive org key:

Copiedvar userOrgSharedKey = SHARINGKEY;
var userPrivateKey = PRIVATEKEY;
var orgKey = null;
if((userPrivateKey !="null")&&(userOrgSharedKey!="null")){
    orgKey = Vault.RSA_decrypt(userOrgSharedKey, Vault.decrypt(userPrivateKey, masterkey)); 
}

Step 5 - Decrypting password data:

The JSON response from Step 3 includes the array of passwords, which we have to decrypt. Sample password details from the JSON response are updated on your right.

Here, the encrypted contents are CUSTOMCOLUMN, SECURENOTE & PASSWORDDATA. Please note the value for ISSHARED which defines, whether a particular password is encrypted with org key or using the master key. If the ISSHARED value is “YES”, data has to be decrypted using the Org Key, which is already received from step 4. If the value is “No”, the data has to be decrypted using user’s Master key, derived from step 2. To obtain the proper password data label, always refer the PASSWORDTYPEID against the array of PASSWORDTYPECOLUMNS.

Step 5 - Example

CopiedHTTP/1.1 201 Created
Content-Type:application/json;charset=UTF-8
"SECRETS":[ {
"SHARING":{ "DETAILS":[
{
 "SHAREDTO":"", "SHARINGLEVEL":3, "SHAREDBY":""
} ],
"DIRECTION":"" },
"SECRETID":"2000000926001", "SECRETTYPEID":"2000000000015", "accesssctrlconfigured":"false",
"CUSTOMCOLUMN":"eyJjdXN0b21jb2wiOlt7ImNvbG5hbWUiOiJhYSIsInZhbHVlIjoic1FHbThpMHh WVmZFbFE9PSIsInR5cGUiOiJ0ZXh0IiwiaWQiOiJjdXN0Q29sRGl2XzAifV19",
"SECRETNAME":"000000_add secrets 1111",


"PASSWORDMODIFIEDTIME":1465200931358, "LASTMODFIEDTIME":1465200950881, "displayaccctrlicon":false, "DESCRIPTION":"asdasdasd", "USERID":"2000000006001", "CREATIONTIME":1465200931358, "SECRETURL":"http://test.com", "ISSHARED":"YES",
"SHARINGLEVEL":10,
 "AUTOLOGIN":false,
 "CLASSIFICATION":"E", "SECURENOTE":"swF1ey0xVVdxjZq4sZz2tY2167o=", "ISSHAREDTOUSERS":false, "POLICYID":"2000000000063",
"SECRETDATA":"{\"username\":\"sAFlvi0xVVct18TZvKuF+nsitPBL\",\"file\":\"sQHq0C0xVVc=\ ",\"password\":\"sAEe4S0xVVeTEVoTapnz3w==\"}",
"AUTOSUBMIT":1, "requeststatus":-1, "ISFAVOURITE":false, "TAGS":"test"
}]

To download or retrieve the attached file from a password using API

Each file attachment in Zoho Vault has a fileID as a reference to it. Supplying the fileID with the API call will help you retrieve the correct attachment. From the required PASSWORDID, under the PASSWORDDATA within the FILES column you will find the “fileID”.

Download or retrieve attached file

CopiedHTTP/1.1 201 Created
Content-Type:application/json;charset=UTF-8
http://vault.zoho.com/api/json/secrets?OPERATION_NAME=GET_SECRET_FILES
Sample FILE column info in secret JSON:
"FILES": "[{"fileId":"1000000004049","name":"query(1).txt","column":"file","expirydate":"","size":113 8}]",

HTTP methods

Zoho Vault API uses appropriate HTTP verbs for every action.

Method	Description
GET	Used for retrieving resources.
POST	Used for creating resources and performing resource actions.
PUT	Used for updating resources.
DELETE	Used for deleting resources.