Create a Rule

You can create a rule and attach conditions to specify which users should be qualified for the rule. Your rule will be created in a staged state so you need to activate it before the users will be added to the manifest.

Remember that a user must match all conditions to be a qualified user for the rule, however they can be qualified for any rule in the ruleset to be added to the ruleset manifest.

When a user matches multiple rules, we apply a unique filter to only attach the user once to a ruleset. When auditing the users in a ruleset, it can be difficult to determine which rule was used to attach a user if the unique is applied randomly. To provide a cleaner audit lens for which users are the exceptions, we apply a weighted priority so rules with the most users (that are presumed to be the most generic at the division or department level usually) are applied first. This ensures that if a user appears twice in a generic and a specific rule, the generic rule is what appears in the policy user mapping data for audit purposes.

POST /policy/rulesets/{ruleset}/rules

Create a Rule

cURL

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

201

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

ruleset · string · required

Policy Ruleset ID

Body

application/json

CreatePolicyRuleRequestData

policy_role_id · string · required

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 short sentence or two that explains the purpose of this rule (ex. audit justification).

If not set, a description is automatically calculated based on conditions.

You can add additional business data to any key name that you'd like in the metadata array

Maximum string length: 255

Example:

"These users provide administration and support for this backoffice system."

expires_after_days · integer | null

Number of days that users are still a manifest user after being deprecated for a graceful transition.

If not set, the ruleset value is used that may be inherited from the workspace default

Required range: 0 <= x <= 1095

Example:

30

priority · integer | null · default: 42

Priority order 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

metadata · string[]

An array of business and context metadata about this rule.

This is cosemetic only for system administrator reference and provides structured data in API responses

Example:

"['managed_by' => 'IT Team', 'access_request_id' => '123456', 'compliance_review_months' => 6]"

Response

201

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