# Replace the MFA enforcement configuration

Replaces your organization's MFA enforcement 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/mfaEnforcement/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 MFA Enforcement 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: Require MFA acknowledgement for Finance

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

  - `rules.mode` (string, required)
    What happens to the accounts a rule matches.
    Enum: "ACKNOWLEDGE", "OFF"

  - `rules.title` (string)
    Heading shown to the user in the acknowledgement prompt. Required when mode is ACKNOWLEDGE.
    Example: Enable MFA

  - `rules.subtext` (string)
    Message shown to the user in the acknowledgement prompt. Markdown is supported. Required when mode is ACKNOWLEDGE.
    Example: Your account is missing MFA. Please enable it to continue.

  - `rules.buttonText` (string)
    Label for the acknowledgement button shown to the user. Required when mode is ACKNOWLEDGE.
    Example: I understand

  - `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 accounts by the app they belong to.
    Example: {"matches":["OKTA"]}

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

  - `rules.criteria.appCategories` (object)
    Match accounts by the category of the app they belong to, given as an app category ID.
    Example: {"matches":["9"]}

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

  - `rules.criteria.approvalStatuses` (object)
    Match accounts by the approval status of their app.
    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 accounts by the sensitivity level of their app.
    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"

## Request examples:

  - `Remove all rules` (unknown)

  - `Require an MFA acknowledgement for the Finance group` (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 MFA Enforcement 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: Require MFA acknowledgement for Finance

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

  - `rules.mode` (string, required)
    What happens to the accounts a rule matches.
    Enum: "ACKNOWLEDGE", "OFF"

  - `rules.title` (string)
    Heading shown to the user in the acknowledgement prompt. Required when mode is ACKNOWLEDGE.
    Example: Enable MFA

  - `rules.subtext` (string)
    Message shown to the user in the acknowledgement prompt. Markdown is supported. Required when mode is ACKNOWLEDGE.
    Example: Your account is missing MFA. Please enable it to continue.

  - `rules.buttonText` (string)
    Label for the acknowledgement button shown to the user. Required when mode is ACKNOWLEDGE.
    Example: I understand

  - `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 accounts by the app they belong to.
    Example: {"matches":["OKTA"]}

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

  - `rules.criteria.appCategories` (object)
    Match accounts by the category of the app they belong to, given as an app category ID.
    Example: {"matches":["9"]}

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

  - `rules.criteria.approvalStatuses` (object)
    Match accounts by the approval status of their app.
    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 accounts by the sensitivity level of their app.
    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 400:

  - `400` (unknown)
    Bad Request

## Response 403:

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

## Response 404:

  - `404` (unknown)
    Not Found