# Replace the file download blocking configuration

Replaces your organization's file download blocking configuration with the
configuration you send. Any rule you don't include is deleted.
A rule with an `id` updates the existing rule with that `id`. A rule without
an `id` is created. Rules are evaluated in the order you send them, and the
first rule that matches wins.
To change part of the configuration, retrieve it first, apply your changes,
and send the complete configuration back.

Endpoint: PUT /v1/controls/fileDownloadBlocking/configuration
Version: v1
Security: x-api-key

## Security:

  - `x-api-key` (unknown)
    apiKey in header x-api-key

## Request body:

  - `application/json` (unknown)
    The complete set of rules to save.

## Request fields (application/json):

  - `globals` (object)
    Reserved for control-wide settings. Empty for this control.
    Example: {}

  - `rules` (array, required)
    Complete list of File Download Blocking rules.

  - `rules.id` (string)
    The rule's unique identifier.
    Example: c478966c-f927-411c-b919-179832d3d50c

  - `rules.name` (string, required)
    A short name to help you recognise the rule.
    Example: Block executable downloads for Finance

  - `rules.enabled` (boolean, required)
    Whether the rule is active.
    Example: true

  - `rules.mode` (string, required)
    What happens when a rule matches a file download.
    Enum: "OFF", "MONITOR", "WARN", "BLOCK"

  - `rules.title` (string)
    Heading shown to the user. Required when mode is WARN or BLOCK.
    Example: Download blocked

  - `rules.subtext` (string)
    Message shown to the user. Markdown is supported. Required when mode is WARN or BLOCK.
    Example: This file type is not permitted on company devices.

  - `rules.buttonText` (string)
    Label for the button that lets the user continue. Required when mode is WARN, and must not be set for any other mode.
    Example: Download anyway

  - `rules.criteria` (object)
    Restrict the rule to apply only under the specified conditions.

  - `rules.criteria.employeeIds` (object)
    Match specific employees by their employee identifier.
    Example: {"matches":["8c4f1d2e-9a0b-4c1d-8e2f-3a4b5c6d7e8f"]}

  - `rules.criteria.employeeIds.matches` (array, required)
    One or more values to match.

  - `rules.criteria.employeeIds.action` (string)
    Apply the rule to the matched values (INCLUDE) or to everything except them (EXCLUDE). Defaults to INCLUDE when omitted.
    Enum: "INCLUDE", "EXCLUDE"

  - `rules.criteria.employeeGroups` (object)
    Match employees by the groups they belong to.
    Example: {"matches":["Finance","Engineering"]}

  - `rules.criteria.fileNames` (object)
    Match downloads by exact file name.
    Example: {"matches":["secret.txt"]}

  - `rules.criteria.fileNamePatterns` (object)
    Match downloads whose file name matches a regular expression.
    Example: {"matches":[".*\\.pdf"]}

  - `rules.criteria.fileNamePatterns.matches` (array, required)
    One or more values to match.

  - `rules.criteria.fileExtensions` (object)
    Match downloads by file extension. Each value must begin with a dot, such as .exe or .zip.
    Example: {"matches":[".exe",".zip"]}

  - `rules.criteria.urlPatterns` (object)
    Match downloads by the URL they came from. Each value must be a `*://`-prefixed URL pattern.
    Example: {"matches":["*://*.example.com/"]}

  - `rules.criteria.profileScope` (object)
    Match by the profile in use on the browser. If omitted, defaults to ALL.

  - `rules.criteria.profileScope.matches` (array, required)
    A single value: ALL (any logged in profile), COMPANY_DOMAIN (profiles for your company domains), or NON_COMPANY_DOMAIN (profiles outside your company domains).
    Example: ["COMPANY_DOMAIN"]

## Request examples:

  - `Remove all rules` (unknown)

  - `Block executable downloads for the Finance group on company domains` (unknown)

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `globals` (object)
    Reserved for control-wide settings. Empty for this control.
    Example: {}

  - `rules` (array, required)
    Complete list of File Download Blocking rules.

  - `rules.id` (string)
    The rule's unique identifier.
    Example: c478966c-f927-411c-b919-179832d3d50c

  - `rules.name` (string, required)
    A short name to help you recognise the rule.
    Example: Block executable downloads for Finance

  - `rules.enabled` (boolean, required)
    Whether the rule is active.
    Example: true

  - `rules.mode` (string, required)
    What happens when a rule matches a file download.
    Enum: "OFF", "MONITOR", "WARN", "BLOCK"

  - `rules.title` (string)
    Heading shown to the user. Required when mode is WARN or BLOCK.
    Example: Download blocked

  - `rules.subtext` (string)
    Message shown to the user. Markdown is supported. Required when mode is WARN or BLOCK.
    Example: This file type is not permitted on company devices.

  - `rules.buttonText` (string)
    Label for the button that lets the user continue. Required when mode is WARN, and must not be set for any other mode.
    Example: Download anyway

  - `rules.criteria` (object)
    Restrict the rule to apply only under the specified conditions.

  - `rules.criteria.employeeIds` (object)
    Match specific employees by their employee identifier.
    Example: {"matches":["8c4f1d2e-9a0b-4c1d-8e2f-3a4b5c6d7e8f"]}

  - `rules.criteria.employeeIds.matches` (array, required)
    One or more values to match.

  - `rules.criteria.employeeIds.action` (string)
    Apply the rule to the matched values (INCLUDE) or to everything except them (EXCLUDE). Defaults to INCLUDE when omitted.
    Enum: "INCLUDE", "EXCLUDE"

  - `rules.criteria.employeeGroups` (object)
    Match employees by the groups they belong to.
    Example: {"matches":["Finance","Engineering"]}

  - `rules.criteria.fileNames` (object)
    Match downloads by exact file name.
    Example: {"matches":["secret.txt"]}

  - `rules.criteria.fileNamePatterns` (object)
    Match downloads whose file name matches a regular expression.
    Example: {"matches":[".*\\.pdf"]}

  - `rules.criteria.fileNamePatterns.matches` (array, required)
    One or more values to match.

  - `rules.criteria.fileExtensions` (object)
    Match downloads by file extension. Each value must begin with a dot, such as .exe or .zip.
    Example: {"matches":[".exe",".zip"]}

  - `rules.criteria.urlPatterns` (object)
    Match downloads by the URL they came from. Each value must be a `*://`-prefixed URL pattern.
    Example: {"matches":["*://*.example.com/"]}

  - `rules.criteria.profileScope` (object)
    Match by the profile in use on the browser. If omitted, defaults to ALL.

  - `rules.criteria.profileScope.matches` (array, required)
    A single value: ALL (any logged in profile), COMPANY_DOMAIN (profiles for your company domains), or NON_COMPANY_DOMAIN (profiles outside your company domains).
    Example: ["COMPANY_DOMAIN"]

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 403:

  - `403` (unknown)
    Forbidden (read-only API key)

## Response 404:

  - `404` (unknown)
    Not Found