Create a Rule

curl --request POST \
  --url https://wksusa1b2c3d.provisionr.app/api/v1/policy/rulesets/{ruleset}/rules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "policy_role_id": "porol_01hq8xyzabc123def456ghi789",
  "description": "These users provide administration and support for this backoffice system.",
  "expires_after_days": 30,
  "priority": 42,
  "metadata": "['managed_by' => 'IT Team', 'access_request_id' => '123456', 'compliance_review_months' => 6]"
}
EOF

$headers=@{}
$headers.Add("Authorization", "Bearer <token>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://wksusa1b2c3d.provisionr.app/api/v1/policy/rulesets/{ruleset}/rules' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "policy_role_id": "porol_01hq8xyzabc123def456ghi789",
  "description": "These users provide administration and support for this backoffice system.",
  "expires_after_days": 30,
  "priority": 42,
  "metadata": "['managed_by' => 'IT Team', 'access_request_id' => '123456', 'compliance_review_months' => 6]"
}'

import requests

url = "https://wksusa1b2c3d.provisionr.app/api/v1/policy/rulesets/{ruleset}/rules"

payload = {
    "policy_role_id": "porol_01hq8xyzabc123def456ghi789",
    "description": "These users provide administration and support for this backoffice system.",
    "expires_after_days": 30,
    "priority": 42,
    "metadata": "['managed_by' => 'IT Team', 'access_request_id' => '123456', 'compliance_review_months' => 6]"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    policy_role_id: 'porol_01hq8xyzabc123def456ghi789',
    description: 'These users provide administration and support for this backoffice system.',
    expires_after_days: 30,
    priority: 42,
    metadata: '[\'managed_by\' => \'IT Team\', \'access_request_id\' => \'123456\', \'compliance_review_months\' => 6]'
  })
};

fetch('https://wksusa1b2c3d.provisionr.app/api/v1/policy/rulesets/{ruleset}/rules', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "porul_01hq8xyzabc123def456ghi789",
  "state": "active",
  "role_name": "Group Member",
  "role_handle": "member",
  "is_imported": true,
  "description": "<string>",
  "metadata": [
    "<string>"
  ],
  "expires_after_days": 123,
  "expires_after_days_inherited": true,
  "priority": 42,
  "timestamp": {
    "created_at": "2025-01-28T13:37:00Z",
    "updated_at": "2025-05-04T03:27:00Z",
    "activated_at": "2025-03-14T15:07:00Z",
    "expires_at": null,
    "deleted_at": null
  },
  "count": {
    "policy_conditions": 123,
    "manifest_users": 123,
    "qualified_users": 123,
    "staged_users": 123,
    "audit_logs_parent": 123,
    "audit_logs_record": 123,
    "audit_logs_related": 123
  },
  "included": {
    "policy_conditions": [
      {
        "id": "pocon_01hq8xyzabc123def456ghi789",
        "is_imported": true,
        "type": "attribute",
        "ruleset_id": "poset_01hq8xyzabc123def456ghi789",
        "rule_id": "porul_01hq8xyzabc123def456ghi789",
        "resource_id": "dratr_01hq8xyzabc123def456ghi789",
        "profile_key": "department",
        "profile_operator": "equals",
        "profile_value": "IT Helpdesk",
        "description": "<string>"
      }
    ],
    "policy_role": {
      "id": "<string>"
    },
    "policy_ruleset": {
      "id": "poset_01hq8xyzabc123def456ghi789",
      "state": "unmanaged",
      "type": "directory_attribute",
      "resource_id": "dratr_01hq8xyzabc123def456ghi789",
      "is_authoritative": false,
      "expires_after_days": 30
    }
  },
  "links": {
    "self": "<string>",
    "policy_conditions": "<string>",
    "policy_ruleset": "<string>",
    "policy_resource": "<string>",
    "manifest_users": "<string>",
    "qualified_users": "<string>",
    "staged_users": "<string>",
    "audit_logs_parent": "<string>",
    "audit_logs_record": "<string>",
    "audit_logs_related": "<string>"
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "errors": {}
}

Policy Rules

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 --request POST \
  --url https://wksusa1b2c3d.provisionr.app/api/v1/policy/rulesets/{ruleset}/rules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "policy_role_id": "porol_01hq8xyzabc123def456ghi789",
  "description": "These users provide administration and support for this backoffice system.",
  "expires_after_days": 30,
  "priority": 42,
  "metadata": "['managed_by' => 'IT Team', 'access_request_id' => '123456', 'compliance_review_months' => 6]"
}
EOF

$headers=@{}
$headers.Add("Authorization", "Bearer <token>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://wksusa1b2c3d.provisionr.app/api/v1/policy/rulesets/{ruleset}/rules' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "policy_role_id": "porol_01hq8xyzabc123def456ghi789",
  "description": "These users provide administration and support for this backoffice system.",
  "expires_after_days": 30,
  "priority": 42,
  "metadata": "['managed_by' => 'IT Team', 'access_request_id' => '123456', 'compliance_review_months' => 6]"
}'

import requests

url = "https://wksusa1b2c3d.provisionr.app/api/v1/policy/rulesets/{ruleset}/rules"

payload = {
    "policy_role_id": "porol_01hq8xyzabc123def456ghi789",
    "description": "These users provide administration and support for this backoffice system.",
    "expires_after_days": 30,
    "priority": 42,
    "metadata": "['managed_by' => 'IT Team', 'access_request_id' => '123456', 'compliance_review_months' => 6]"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    policy_role_id: 'porol_01hq8xyzabc123def456ghi789',
    description: 'These users provide administration and support for this backoffice system.',
    expires_after_days: 30,
    priority: 42,
    metadata: '[\'managed_by\' => \'IT Team\', \'access_request_id\' => \'123456\', \'compliance_review_months\' => 6]'
  })
};

fetch('https://wksusa1b2c3d.provisionr.app/api/v1/policy/rulesets/{ruleset}/rules', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "porul_01hq8xyzabc123def456ghi789",
  "state": "active",
  "role_name": "Group Member",
  "role_handle": "member",
  "is_imported": true,
  "description": "<string>",
  "metadata": [
    "<string>"
  ],
  "expires_after_days": 123,
  "expires_after_days_inherited": true,
  "priority": 42,
  "timestamp": {
    "created_at": "2025-01-28T13:37:00Z",
    "updated_at": "2025-05-04T03:27:00Z",
    "activated_at": "2025-03-14T15:07:00Z",
    "expires_at": null,
    "deleted_at": null
  },
  "count": {
    "policy_conditions": 123,
    "manifest_users": 123,
    "qualified_users": 123,
    "staged_users": 123,
    "audit_logs_parent": 123,
    "audit_logs_record": 123,
    "audit_logs_related": 123
  },
  "included": {
    "policy_conditions": [
      {
        "id": "pocon_01hq8xyzabc123def456ghi789",
        "is_imported": true,
        "type": "attribute",
        "ruleset_id": "poset_01hq8xyzabc123def456ghi789",
        "rule_id": "porul_01hq8xyzabc123def456ghi789",
        "resource_id": "dratr_01hq8xyzabc123def456ghi789",
        "profile_key": "department",
        "profile_operator": "equals",
        "profile_value": "IT Helpdesk",
        "description": "<string>"
      }
    ],
    "policy_role": {
      "id": "<string>"
    },
    "policy_ruleset": {
      "id": "poset_01hq8xyzabc123def456ghi789",
      "state": "unmanaged",
      "type": "directory_attribute",
      "resource_id": "dratr_01hq8xyzabc123def456ghi789",
      "is_authoritative": false,
      "expires_after_days": 30
    }
  },
  "links": {
    "self": "<string>",
    "policy_conditions": "<string>",
    "policy_ruleset": "<string>",
    "policy_resource": "<string>",
    "manifest_users": "<string>",
    "qualified_users": "<string>",
    "staged_users": "<string>",
    "audit_logs_parent": "<string>",
    "audit_logs_record": "<string>",
    "audit_logs_related": "<string>"
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "errors": {}
}

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

Minimum array length: 1

Example:

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

Response

PolicyRuleDetailedResponseData

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 | null

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

Getting Started

Endpoints

Create a Rule

Authorizations

Path Parameters

Body

Response