Secrets

Designate the value of a String property in your Data Schema as "secret": true and Contextual will encrypt the value provided and keep it in a key store, so that it is only ever shown in Tenant Workspace UI Data Grids and JSON code views as <ENCRYPTED>, and only initially shown in Record editing forms in the Tenant Workspace UI as ••••••••, together with an Eye icon that when clicked will retrieve and reveal the secret value, only for users that have Create or Update permissions for the Object Type.

    "mySecretProperty": {
      "description": "Values will be encrypted and stored as a secret",
      "type": "string",
      "secret": true
    }

How Secrets are Returned and Revealed Using the Tenant API

When working with Records of an Object Type using the Tenant API, if secrets exist, the response for a GET of a specific Record, would look something like the following example, where the value of the secret is returned only as <ENCRYPTED>, and the "secrets" array is populated with the path of the property that was designated as secret.

Retrieving a Record that Contains a Secret

{
    "invoiceId": "0826ccf4-626c-4d3f-af99-19ced46b19ab",
    "mySecretProperty": "<ENCRYPTED>",
    "_metaData": {
        "createdAt": "2024-05-09T17:56:53.256Z",
        "hash": "20b26377236d3f7daa9e50d1fba34374b28ff6d29378b468ca42c448d43b0bd4",
        "id": "0826ccf4-626c-4d3f-af99-19ced46b19ab",
        "schema": "native-object:example",
        "type": "custom",
        "updatedAt": "2024-05-09T17:56:53.256Z",
        "secrets": [
            "mySecretProperty"
        ]
    }
}

Assuming the Tenant API Key you are using has Create or Update permissions, and as documented in the Tenant API Swagger for each of your Object Types, you can then reveal the secret using a second call - specifically, a POST to /$secrets with the path of the secret property for which you want to reveal the value. The response to such a call is simply the value of the secret property:

Retrieving a Secret Value with /$secrets

{
    "value": "mySecret"
}