Add and configure user-supplied secrets

The Live Systems Data service provides mechanisms for communicating with external sources of information.

The user secrets service lets you add credentials for external sources, platforms, or environments to use when configuring data connectors or the facility simulator.

You can access the user secrets service through the Live Systems Data API.

Create a user secret

User secrets are associated with a given workspace and facility ID. User secrets are defined with a name and payload. The following are the naming guidelines for the name and payload:

  • Name
    • Must only contain alphanumeric characters and dashes (^[a-zA-Z0-9-]+$)
    • Must be between 1 and 64 characters in length
  • Payload
    • Must be a minimum of 1 character in length

Send a POST request to /api/live/v1/workspaces/{workspaceId}/facilities/{facilityId}/user-secrets with a body including the name and payload:

{
  "name": "My-Sample-IotHub-EventHub-ConnectionString",
  "payload": "Endpoint=sb://iothub-ns-my-sample-iot-hub.servicebus.windows.net/;SharedAccessKeyName=iothubowner;SharedAccessKey=xxxxxxxxxxxxxxxxxx;EntityPath=my-sample-iot-hub"
}

Update a user secret payload

You can update existing user secrets with new payloads. User secrets are immutable, which means a new version is created when you update the payload.

Send a PUT request to /api/live/v1/workspaces/{workspaceId}/facilities/{facilityId}/user-secrets/{secretId} with a body including the new payload:

{
  "payload": "Endpoint=sb://iothub-ns-my-new-sample-iot-hub.servicebus.windows.net/;SharedAccessKeyName=iothubowner;SharedAccessKey=xxxxxxxxxxxxxxxxxx;EntityPath=my-new-sample-iot-hub"
}

User secrets

For security reasons, secret payloads cannot be retrieved from this API. Only metadata associated with the secret is returned.

Use the user secret's id property when configuring a data connector or facility simulator that requires a secret.

[
  {
    "id": "user-secret_debc6cc2-0f4e-430a-a6e2-7007b5158b3b_My-Sample-IotHub-EventHub-ConnectionString",
    "created": "2023-01-27T16:35:20.783908+00:00",
    "expiring": null,
    "versions": [
      {
        "id": "2",
        "state": "Enabled",
        "created": "2023-01-27T16:39:43.189044+00:00",
        "deleted": null
      },
      {
        "id": "1",
        "state": "Disabled",
        "created": "2023-01-27T16:35:21.133089+00:00",
        "deleted": null
      }
    ]
  }
]

Endpoints

Refer to the Live Systems Data REST API documentation for information about the REST API endpoints available for configuring user secrets.