# Replace the app banner configuration

Replaces your organization's app banner 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/appBanner/configuration
Version: v1
Security: x-api-key

## Request fields (application/json):

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

  - `rules` (array, required)
    Complete list of App Banner 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: Warn Finance about risky apps

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

  - `rules.mode` (string, required)
    What banner (if any) is shown when the rule matches.
    Enum: "INFORM", "ACKNOWLEDGE", "REASON", "BLOCK", "DO_NOT_SHOW"

  - `rules.title` (string)
    Heading shown to the user. Required for every mode except DO_NOT_SHOW.
    Example: Approved apps only

  - `rules.subtext` (string)
    Message shown to the user. Markdown is supported. Required for every mode except DO_NOT_SHOW.
    Example: Please only use apps approved by IT.

  - `rules.buttonText` (string)
    Label for the banner's action button. Required for modes ACKNOWLEDGE and REASON, and for BLOCK when allowReasonSubmission is true. Must not be set for mode INFORM.
    Example: I understand

  - `rules.allowReasonSubmission` (boolean)
    Whether the user may submit a reason. Only valid for mode BLOCK, where it is required.
    Example: true

  - `rules.displayFrequency` (string)
    How often the banner is shown to a matching user.
    Enum: "ONCE_PER_BROWSER", "ONCE_PER_TAB"

  - `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.appTypes` (object)
    Match apps by their type.
    Example: {"matches":["OKTA"]}

  - `rules.criteria.appLabels` (object)
    Match apps by the labels applied to them.
    Example: {"matches":["Sanctioned"]}

  - `rules.criteria.appCategories` (object)
    Match apps by their category.
    Example: {"matches":["9"]}

  - `rules.criteria.appCategories.matches` (array, required)
    One or more app category IDs to match.

  - `rules.criteria.approvalStatuses` (object)
    Match apps by their approval status.
    Example: {"matches":["APPROVED"]}

  - `rules.criteria.approvalStatuses.matches` (array, required)
    One or more approval statuses to match.

  - `rules.criteria.approvalStatuses.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.sensitivityLevels` (object)
    Match apps by their sensitivity level.
    Example: {"matches":["HIGH"]}

  - `rules.criteria.sensitivityLevels.matches` (array, required)
    One or more sensitivity levels to match.

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

## Response 200 fields (application/json):

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

  - `rules` (array, required)
    Complete list of App Banner 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: Warn Finance about risky apps

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

  - `rules.mode` (string, required)
    What banner (if any) is shown when the rule matches.
    Enum: "INFORM", "ACKNOWLEDGE", "REASON", "BLOCK", "DO_NOT_SHOW"

  - `rules.title` (string)
    Heading shown to the user. Required for every mode except DO_NOT_SHOW.
    Example: Approved apps only

  - `rules.subtext` (string)
    Message shown to the user. Markdown is supported. Required for every mode except DO_NOT_SHOW.
    Example: Please only use apps approved by IT.

  - `rules.buttonText` (string)
    Label for the banner's action button. Required for modes ACKNOWLEDGE and REASON, and for BLOCK when allowReasonSubmission is true. Must not be set for mode INFORM.
    Example: I understand

  - `rules.allowReasonSubmission` (boolean)
    Whether the user may submit a reason. Only valid for mode BLOCK, where it is required.
    Example: true

  - `rules.displayFrequency` (string)
    How often the banner is shown to a matching user.
    Enum: "ONCE_PER_BROWSER", "ONCE_PER_TAB"

  - `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.appTypes` (object)
    Match apps by their type.
    Example: {"matches":["OKTA"]}

  - `rules.criteria.appLabels` (object)
    Match apps by the labels applied to them.
    Example: {"matches":["Sanctioned"]}

  - `rules.criteria.appCategories` (object)
    Match apps by their category.
    Example: {"matches":["9"]}

  - `rules.criteria.appCategories.matches` (array, required)
    One or more app category IDs to match.

  - `rules.criteria.approvalStatuses` (object)
    Match apps by their approval status.
    Example: {"matches":["APPROVED"]}

  - `rules.criteria.approvalStatuses.matches` (array, required)
    One or more approval statuses to match.

  - `rules.criteria.approvalStatuses.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.sensitivityLevels` (object)
    Match apps by their sensitivity level.
    Example: {"matches":["HIGH"]}

  - `rules.criteria.sensitivityLevels.matches` (array, required)
    One or more sensitivity levels to match.

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