Sync a Ruleset

A ruleset is automatically synced when a Attribute or Resource is synced. There is no need to sync a ruleset manually unless you need a real-time update and want to dispatch a sync job immediately using this endpoint.

POST /policy/rulesets/{ruleset}/sync

Sync a Ruleset

cURL

curl --request POST \
  --url https://wks-a1b2c3d4.provisionr.io/api/v1/policy/rulesets/{ruleset}/sync \
  --header 'Authorization: Bearer <token>'

202

{
  "id": "<string>",
  "state": "unmanaged",
  "resource_type": "directory_attribute",
  "resource_id": "<string>",
  "resource_parent": "<string>",
  "resource_name": "<string>",
  "resource_handle": "<string>",
  "is_authoritative": true,
  "expires_after_days": 123,
  "count": {
    "policy_ruleset_admins": 123,
    "policy_conditions": 123,
    "policy_rules": 123,
    "manifest_users": 123,
    "qualified_users": 123,
    "staged_users": 123,
    "workspace_logs_parent": 123,
    "workspace_logs_record": 123,
    "workspace_logs_related": 123
  },
  "included": {
    "policy_resource": "<unknown>",
    "policy_ruleset_admins": [
      {
        "id": "<string>",
        "state": "staged",
        "role": "admin",
        "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"
        },
        "included": {
          "directory_user": {
            "id": "<string>",
            "state": "staged",
            "manager_id": "<string>",
            "is_manager": true,
            "full_name": "<string>",
            "email": "<string>",
            "username": "<string>",
            "org": {},
            "metadata": {}
          },
          "policy_ruleset": {
            "id": "<string>",
            "state": "unmanaged",
            "type": "directory_attribute",
            "resource_id": "<string>",
            "is_authoritative": true,
            "expires_after_days": 123
          }
        },
        "links": {
          "self": "<string>",
          "directory_user": "<string>",
          "policy_ruleset": "<string>"
        }
      }
    ],
    "policy_rules": [
      {
        "id": "<string>",
        "state": "staged",
        "role_name": "<string>",
        "role_handle": "<string>",
        "is_imported": true,
        "description": "<string>",
        "expires_after_days": 123,
        "expires_after_days_inherited": true,
        "priority": 123
      }
    ],
    "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>"
      }
    ]
  },
  "links": {
    "self": "<string>",
    "policy_resource": "<string>",
    "policy_ruleset_admins": "<string>",
    "policy_rules": "<string>",
    "policy_conditions": "<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

Response

202

application/json

PolicyRulesetDetailedResponseData

id · string · required

Example:

"poset_01hq8xyzabc123def456ghi789"

state · enum<string> · required

The state of the policy ruleset and whether the group or resource is being managed

unmanaged The Workspace Integration sync detected this existing group or resource. Until you change the ruleset to monitored or managed, Provisionr simply sees that it exists but will not perform API calls to detect users. No rules or conditions can be created until a ruleset is changed to managed. Any unmanaged groups and resources are hidden from most user interfaces to reduce clutter. An unmanaged ruleset is not counted as an active policy for billing purposes.
monitored The Workspace Integration sync is performing read-only monitoring for this group or resource to detect changes, however no API calls are made to add or remove users. This allows you to see an audit trail of changes in user membership over time without managing rules and conditions. Recommendations for rules and conditions will still be generated based on user membership changes for insights. You can change the ruleset to managed to start creating rules and conditions. A monitored ruleset does count as an active policy for billing purposes.
managed The Workspace Integration sync is actively managing this group or resource and provisioning and deprovisioning users based on the rules and conditions defined. By default, is_authoritative is set to false. Administrators can create rules and conditions to manage users, however any unmanaged group or resource users detected during syncs are ignored (not removed). If is_authoritative is set to true, any unmanaged users detected during syncs are removed from the group or resource. The Provisionr database maintains a record of them for auditing purposes and ability to restore them later if needed. A managed ruleset does count as an active policy for billing purposes.

Available options: unmanaged, monitored, managed

resource_type · enum<string> · required

The type of resource that this policy ruleset applies to

directory_attribute Provisionr Dimension Attribute. This acts as a reusable ruleset for other Attributes, Groups or Resources
gitlab_group GitLab Group. This is used for granting access to child groups and projects, or inviting membership groups to other groups or projects.
gitlab_project GitLab Project. This is used for managing members of a specific project.
google_drive_doc Google Drive Document. This is used for managing members of a Google Docs file.
google_drive_file Google Drive File. This is used for managing members of a Google Drive uploaded file (ex. PDF).
google_drive_folder Google Drive Folder. This is used for managing members of a Google Drive folder.
google_drive_deck Google Drive Slidedeck. This is used for managing members of a Google Slides file.
google_drive_sheet Google Drive Spreadsheet. This is used for managing members of a Google Sheets file.
google_identity_group Google Cloud Identity Group. This is used for Cloud Identity Groups that can be used for access management.
google_workspace_drive Google Workspace Shared Drive. This is used for managing members of a Google Shared Drive in Google Workspace.
google_workspace_group Google Workspace Group. This is used for Workspace Groups that can be used for email distribution lists and access management.
okta_group Okta Group. This is used for managing members of a group that is assigned to one or more to Okta Apps.
slack_connect_channel Slack Connect Channel.
slack_public_channel Slack Public Channel. This is used for inviting users to Slack public channels.
slack_private_channel Slack Private Channel. This is used for inviting users to Slack private channels.
slack_group Slack User Group. This can be used for taggable user groups or adding user groups to channels.

Available options: directory_attribute, gitlab_group, gitlab_project, google_drive_doc, google_drive_file, google_drive_folder, google_drive_deck, google_drive_sheet, google_identity_group, google_workspace_drive, google_workspace_group, okta_group, slack_connect_channel, slack_public_channel, slack_private_channel, slack_group

Example:

"directory_attribute"

resource_id · string · required

The ID of the resource that this policy ruleset applies to

Examples:

"dratr_01hq8xyzabc123def456ghi789"

"glgrp_01hq8xyzabc123def456ghi789"

"glprj_01hq8xyzabc123def456ghi789"

"gddoc_01hq8xyzabc123def456ghi789"

"gdfil_01hq8xyzabc123def456ghi789"

"gdfol_01hq8xyzabc123def456ghi789"

"gddck_01hq8xyzabc123def456ghi789"

"gdsht_01hq8xyzabc123def456ghi789"

"gigrp_01hq8xyzabc123def456ghi789"

"gwdrv_01hq8xyzabc123def456ghi789"

"gwgrp_01hq8xyzabc123def456ghi789"

"okgrp_01hq8xyzabc123def456ghi789"

"slgrp_01hq8xyzabc123def456ghi789"

"slprv_01hq8xyzabc123def456ghi789"

"slpub_01hq8xyzabc123def456ghi789"

resource_parent · string · required

The parent name of the resource that this policy ruleset applies to

Example:

"Department"

resource_name · string · required

The name of the resource that this policy ruleset applies to

Example:

"Engineering"

resource_handle · string · required

The handle of the resource that this policy ruleset applies to

Example:

"eng"

is_authoritative · boolean · required

Whether this ruleset is authoritative for managing users on the resource. If true, only users that match a Provisionr policy rule will remain a member of the group or resource, and unmanaged users will be removed during each sync. If false, users added outside of Provisionr will not be removed

Example:

false

expires_after_days · integer · required

This shows the value for the parent attribute or resource.

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 > Ruleset > Rule 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

Example:

30

count · object · required

Counts of related resources

Show child attributes

included · object · required

Included related resources

Show child attributes

links · object · required

API hyperlinks related to the policy ruleset record

Show child attributes