Update a Rule

PATCH /policy/rules/{rule}

Update a Rule

cURL

curl --request PATCH \
  --url https://wks-a1b2c3d4.provisionr.io/api/v1/policy/rules/{rule} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "policy_role_id": "<string>",
  "description": "<string>",
  "expires_after_days": 547,
  "priority": 42
}
'

200

{
  "id": "<string>",
  "state": "staged",
  "role_name": "<string>",
  "role_handle": "<string>",
  "is_imported": true,
  "description": "<string>",
  "metadata": [
    "<string>"
  ],
  "expires_after_days": 123,
  "expires_after_days_inherited": true,
  "priority": 123,
  "timestamp": {
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "activated_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z"
  },
  "count": {
    "policy_conditions": 123,
    "manifest_users": 123,
    "qualified_users": 123,
    "staged_users": 123,
    "workspace_logs_parent": 123,
    "workspace_logs_record": 123,
    "workspace_logs_related": 123
  },
  "included": {
    "policy_conditions": [
      {
        "id": "<string>",
        "is_imported": true,
        "type": "attribute",
        "ruleset_id": "<string>",
        "rule_id": "<string>",
        "resource_id": "<string>",
        "profile_key": "<string>",
        "profile_operator": "equals",
        "profile_value": "<string>",
        "description": "<string>"
      }
    ],
    "policy_role": {
      "id": "<string>"
    },
    "policy_ruleset": {
      "id": "<string>",
      "state": "unmanaged",
      "type": "directory_attribute",
      "resource_id": "<string>",
      "is_authoritative": true,
      "expires_after_days": 123
    }
  },
  "links": {
    "self": "<string>",
    "policy_conditions": "<string>",
    "policy_ruleset": "<string>",
    "policy_resource": "<string>",
    "manifest_users": "<string>",
    "qualified_users": "<string>",
    "staged_users": "<string>",
    "workspace_logs_parent": "<string>",
    "workspace_logs_record": "<string>",
    "workspace_logs_related": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

rule · string · required

Policy Rule ID

Body

application/json

UpdatePolicyRuleRequestData

policy_role_id · string

The Vendor role that users matching this rule should be assigned to. The role can only be changed if the rule is in a staged state. After a rule is activated, you will need to create a new rule or duplicate this rule to change the role assignment while it is in a staged state

Pattern: ^porol_[0-9a-hjkmnp-tv-z]{26}$

Example:

"porol_01hq8xyzabc123def456ghi789"

description · string | null

A brief description or justification message for this rule

Maximum string length: 255

Example:

"Engineering department baseline entitlement."

expires_after_days · integer | null

The number of days until user's access is revoked after they no longer qualify for this rule

Required range: 0 <= x <= 1095

Example:

30

priority · integer · default: 42

Priority order between 1 and 99 for evaluating this rule among other rules in the same ruleset.

Lower numbers are evaluated first. Rules with the same priority are evaluated based on the greatest number of users matched (highest to lowest).

Rules for a specific user are always evaluated first (regardless of priority) before other rules to ensure that user-specific elevated roles take precedence.

If not set, the default priority is 42 (obviously...)

Required range: 1 <= x <= 99

Example:

42

Response

200

application/json

PolicyRuleDetailedResponseData

id · string · required

Example:

"porul_01hq8xyzabc123def456ghi789"

state · enum<string> · required

staged The rule is a draft and you can add or remove conditions. Users are not provisioned yet. This is only visible to administrators or in the API. Use the activate method during your change window to provision access to users.
active The rule is active and conditions are locked. You can create a new rule or duplicate an existing rule to customize conditions, and deactivate the old rule after the new rule is activated. Matching users are now Ruleset (Manifest) Users and are provisioned and deprovisioned using the vendor APIs.
expiring The rule is active, however expires_at value is set and is scheduled to expire. If the expires_after_days value is 0, users will lose access immediately when this rule expires.You can run the activate action to remove the scheduled expiration.
expired The expires_at value is in the past and the rule was deactivated. If the user matched a different rule, then they did not lose access.
deactivated The rule was deactivated manually by a ruleset or global admin.

Available options: staged, active, expiring, expired, deactivated

Example:

"active"

role_name · string · required

The name of the vendor role that users matching this rule are assigned to

Example:

"Group Member"

role_handle · string · required

The shorthand handle of the vendor role that users matching this rule are assigned to

Example:

"member"

is_imported · boolean · required

Whether this rule was automatically created when importing a Directory Attribute from a Workspace Integration. You can filter by false values to see rules that were created by an administrator

description · string · required

The description of the rule to provide business justification context. If not set by the user, the condition descriptions are aggregated into the description (if conditions are not a draft)

metadata · string[] | null · required

The rule's custom key/value metadata added by someone or automation in your organization. This is used for business justification, reference IDs, or links to internal issue/tickets for access reviews

expires_after_days · integer | null · required

Users will be automatically deprecated if they no longer qualify for at least one rule in the ruleset.

The expires_after_days value determines how many days after they no longer qualify that they still have access for a graceful transition period when users change job roles.

The value is inherited from the Workspace > Dimension (for Directory Attributes) > Ruleset and can be overridden at any level to provide shorter revoke time controls when needed.

If the value is 0, this skips the grace period and revokes access immediately after expires_at.

By default, users have perpetual access (as Policy Users) as long as their attributes continue to match the conditions for this rule. If this rule is designed for just-in-time or short term access, you can set the expires_at date for all conditional users to be deprecated at that time.

You can use expires_at and expires_after_days=0 together to revoke access immediately

expires_after_days_inherited · boolean · required

Whether this rule expiration was inherited from the ruleset resource or overridden for this rule

priority · integer | null · required

Priority order between 1 and 99 for evaluating this rule among other rules in the same ruleset.

Lower numbers are evaluated first. Rules with the same priority are evaluated based on the greatest number of users matched (highest to lowest).

Rules for a specific user are always evaluated first (regardless of priority) before other rules to ensure that user-specific elevated roles take precedence.

If not set, the default priority is 42 (obviously...)

Example:

42

timestamp · TimestampStateData · object · required

The timestamps for the policy rule record

Show child attributes

count · object · required

Count of related resources

Show child attributes

included · object · required

Included related resources

Show child attributes

links · object · required

API hyperlinks related to the policy rule record

Show child attributes