# Retrieve the app banner configuration

Returns your organization's current app banner configuration, including every rule and its settings. Rules are returned in the order they're evaluated, with the highest-priority rule first.

Endpoint: GET /v1/controls/appBanner/configuration
Version: v1
Security: x-api-key

## 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"