Create a Vault Entry

Manage an Organization Coveo Relevance Cloud System Administrator Product Documentation

In this article

Example

Vault entries are sensitive and restricted key-value pairs stored in the Vault Resource of the Coveo Migration API. The API uses these entries to migrate sensitive information leveraged by your resources, such as credentials used to index content. You can also use vault entries in indexing pipeline extensions (IPEs).

Note

When applying a snapshot to an organization, you can typically use a purpose-built Allow import button to automatically import vault parameters from the origin organization.

If there remain missing vault entries after the import, you need to create them manually.

This article provides an example showing how to create vault entries using the GET /vaultentries/missing and POST /vaultentries endpoints.

Example

You want to apply a snapshot to an organization, but when checking the prerequisites, you receive an error message.

Checking prerequisites when some are missing

You try clicking the Allow import button, but you then receive another error message.

A likely cause is that you have deleted the vault entry from the origin organization.

You therefore use the GET /vaultentries/missing endpoint to see which vault entry is missing.

To make that request, you first need to retrieve the ID of your snapshot. You do so by retrieving the last string of the URL of the target snapshot page in the Administration Console.^[1]

https://platform.cloud.coveo.com/admin/#destinationorganizationid/organization/resource-snapshots/destinationorganizationid-ucbeikkpvxek36wnh4apoe2fnu

Now that you have the target snapshot ID, i.e., destinationorganizationid-ucbeikkpvxek36wnh4apoe2fnu, you make a GET /vaultentries/missing request, setting the snapshotId query parameter value to that ID.

GET https://platform.cloud.coveo.com/rest/organizations/destinationorganizationid/vaultentries/missing?snapshotId=destinationorganizationid-ucbeikkpvxek36wnh4apoe2fnu HTTP/1.1
Accept: application/json
Content-Type: application/json

In the response, you learn that the following vault entry is missing:

{
  "missingVaultEntries": [
    "originorganizationid_iynO7X-configuration.parameters.secretKey.value"
  ]
}

Opening the snapshot JSON, you notice that it’s for the secretKey parameter used as a credential by one of your sources. Depending on the resource, you may see another parameter (e.g., consumerKey) in place of secretKey.

// ...
  "SOURCE": [
    {
      "model": {
        // ...
        "configuration": {
          // ...
          "parameters": {
            // ...
            "secretKey": {
              "sensitive": true,
              "value": "{{ VAULT.originorganizationid_iynO7X-configuration.parameters.secretKey.value }}"
            }
          },
          // ...
        }
        // ...
      }
      // ...
    }
  ]
// ...

You therefore use the POST /vaultentries endpoint to create the target vault entry in your destination organization.

POST https://platform.cloud.coveo.com/rest/organizations/destinationorganizationid/vaultentries HTTP/1.1
Accept: application/json
Content-Type: application/json

Request payload:

{
  "attributeReferences": [
    {
      "jsonPath": "configuration.parameters.secretKey.value", 
      "resourceName": "originorganizationid_iynO7X", 
      "resourceType": "SOURCE"
    }
  ],
  "key": "originorganizationid_iyn07x-configuration.parameters.secretKey.value", 
  "value": "s8h#kj%43s", 
  "organizationId": "destinationorganizationid", 
  "valueType": "STRING",
  "vaultVisibilityType": "OBFUSCATED"
}

	To determine the `jsonPath` value, you open the snapshot JSON content to find out the path to the target key from its parent resource model. In this case, it’s `configuration.parameters.secretKey.value`. `// ... "SOURCE": [ { "model": { // ... "configuration": { // ... "parameters": { // ... "secretKey": { "sensitive": true, "value": "{{ VAULT.originorganizationid_iynO7X-configuration.parameters.secretKey.value }}" } }, // ... } // ... } // ... "resourceName": "originorganizationid_iynO7X" } ] // ...`
	The `resourceName` of the exported resource, which you can find in the snapshot JSON content as well.
	The `key` of the missing vault entry you are creating, namely `originorganizationid_iyn07x-configuration.parameters.secretKey.value`.
	Then, you set the vault entry `value` to `s8h#kj%43s`, which is the credential needed to access the content your source indexes.
	You set the unique identifier of the destination organization as the value of the `organizationId` parameter.

After sending this request, you go back to the Administration Console, refresh your browser, and check that your snapshot prerequisites are now satisfied.

Successful prerequisite check after adding vault entry

1. An alternative would be using the GET /shapshot endpoint to list the snapshots in your organization.