Protecting Secrets

At times it may be useful to limit the visibility of particular fields and values in a flow definition or in a run’s state (for instance, as returned in a run’s event log).

Flows provides two mechanisms to control the visibility of particular fields.

Declaring Private Parameters

You can restrict visibility of fields inside of an action’s Parameters by providing a __Private_Parameters field. If provided, __Private_Parameters is a list of strings that correspond to the names of fields that should be hidden.

This will have the following effects:

When returning a flow definition, Flows will omit fields specified by the __Private_Parameters list unless a user has the flow_administrator or flow_owner role on that flow.
Whenever an action is displayed during a run (including the status and event log), Flows will omit fields specified by the __Private_Parameters list.

Tip

The names in the __Private_Parameters list should correspond to the natural name of the field, excluding any .$ or .= suffix.

Example

{
  "Type": "Action",
  "ActionUrl": "https://example.com/action",
  "Parameters": {
    "server_info": {
      "user_name": "FlowUser",
      "password": "my_password",
      "__Private_Parameters": [
        "password"
      ]
    },
    "End": true
  }
}

In the example action state above, the password field within the server_info object would be omitted by Flows when displaying the definition to a user without the flow_administrator or flow_owner role, as below:

{
  "Type": "Action",
  "ActionUrl": "https://example.com/action",
  "Parameters": {
    "server_info": {
      "user_name": "FlowUser"
    }
  },
  "End": true
}

Important

The __Private_Parameters list does not affect the output of an action. If an action returns a value that includes a field specified in the __Private_Parameters list, that field will be visible in the output, unless protected by another means (see the next section for additional detail on one way accomplish this).

Declaring Private Run State

To limit the visibility of data in a run’s state, Flows will omit fields which begin with the prefix _private from a run’s status and event logs.

Example

{
  "data": {
    "public_data": "This is public",
    "_private_details": {
      "secret": "This should not be shown"
    }
  },
  "_private_data": {
    "password": "my_password"
  }
}

For the example run state above, a user viewing the run’s event log (or status) would see the following:

{
  "data": {
    "public_data": "This is public"
  }
}

Note

If this field (or any of its content) is referenced by path elsewhere in the flow, it is still possible for data in this field to appear in another location. If you need to use a value from a _private field in an action, you should include the name of the referencing field in the action’s __Private_Parameters list (see preceding section for additional detail).

Limitations

While Flows provides mechanisms to limit the visibility of data, it is important to note that these mechanisms are not foolproof.

For example, if an action raises an uncaught exception (for instance, due to a failed schema validation), the error content may expose the value of a field that would have otherwise been omitted. Verifying the output of your actions and restricting user input by providing an input schema can help to mitigate this risk.

Additionally, it’s important to know that this functionality is provided by Flows alone, and action providers are not aware of the visibility restrictions you have set. Thus, action providers may still return data in their output that you have marked as private in your flow definition. Please refer to the privacy policy of the action provider, if available, to understand if and/or how they handle sensitive data, and to ensure you trust the maintainers of the action provider with any data you provide.

You should ensure that your flow definition is designed with these limitations in mind, and that it has been adequately tested to ensure that sensitive data is not inadvertently exposed.