> ## Documentation Index
> Fetch the complete documentation index at: https://docs.provisionr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies & Rules

> Each group or resource maps to one Policy Ruleset whose rules and conditions determine which users qualify for access, evaluated during every sync.

Now that you know how Provisionr turns your users' profile data into dimensions and attributes, you can look at how those attributes are used to decide who gets access. Every group or resource that Provisionr integrates with has a 1:1 mapping to a policy, which defines the conditions that a user must meet to be granted access to that group or resource.

Policies aren't reusable, so no two groups or resources share the same policy. When several groups need the same logic, you reuse an attribute in each of their policies instead, as [Attribute Conditions](#attribute-conditions) explains.

![Separate Policies per Group](https://mintcdn.com/provisionr/VNq5QTz41OqBybRj/images/diagrams/architecture/intro/concepts/concepts-policy-resource-separation.svg?fit=max\&auto=format\&n=VNq5QTz41OqBybRj\&q=85\&s=509b8128368bd0eca83790a458f86cd2)

Each group has a 1:1 relationship with a policy.

This page explains how a policy is put together from rulesets, rules, and conditions, how each type of condition matches people, and how rule priority and expiration dates shape the access that a policy grants.

## Policy Rulesets

A policy can have *one or more* **Policy Rules**, and together they form a set of rules that we call a **Policy Ruleset**. Each rule, in turn, holds the conditions that a user has to match.

![A ruleset with rules and conditions](https://mintcdn.com/provisionr/VNq5QTz41OqBybRj/images/diagrams/architecture/policy/intro/policy-intro-overview.svg?fit=max\&auto=format\&n=VNq5QTz41OqBybRj\&q=85\&s=f936e360d767eb8fa0acc985f4615c1a)

A ruleset holds rules, and each rule holds conditions.

> [!NOTE]
>
> Throughout the documentation, we use **Policy**, **Ruleset**, and **Policy Ruleset** interchangeably, and they all refer to the same thing. The official name is **Policy Ruleset**, but we often say **Policy** or **Ruleset** for short.

## Imported Attribute Rulesets

When you connect an integration and import its groups or resources, Provisionr automatically creates a Policy Ruleset for each group or resource that you imported. The same is true of the attributes that we import from your users' profile data, as [Dimensions & Attributes](https://docs.provisionr.io/concepts/control/dimensions.md) describes, so every imported attribute has a ruleset of its own. For example, an integration might give you these counts of imported attributes for each dimension.

```json Count of Imported Attributes theme={null}
{
    "Cost Center": 3,
    "Division": 8,
    "Department": 28,
    "Title": 131,
}
```

You'll see the Policy Ruleset ID in the `policy_ruleset_id` field of every attribute, group, and resource record in Provisionr. Here is the `IT` attribute, followed by its ruleset.

```json IT Department Attribute Data highlight={6} theme={null}
{
    "id": "dratr_01kgstavxctryyfg46k2dnepqc",
    "integration_id": "okitg_01kgst0661n7j9natpk42xp12v",
    "directory_dimension_id": "drdim_01kgst085d5jr6pq2mvzxa9hae",
    "directory_attribute_id_successor": null,
    "policy_ruleset_id": "poset_01kgstavy0q6s4bkbsj08n25ts",
    "type": "integration",
    "profile_value": "IT",
    "blueprint_signature": null,
    "name": "IT",
    "handle": "it",
    "metadata": [],
    "conditions_enabled": true,
    "created_at": "2026-02-06T15:50:05.000000Z",
    "updated_at": "2026-02-06T15:50:06.000000Z",
    "activated_at": "2026-02-06T15:50:05.000000Z",
    "expires_at": null,
    "deleted_at": null,
    "state": "active",
}
```

```json Policy Ruleset for IT Department Attribute theme={null}
{
    "id": "poset_01kgstavy0q6s4bkbsj08n25ts",
    "type": "directory_attribute",
    "resource_id": "dratr_01kgstavxctryyfg46k2dnepqc",
    "sync_enabled": true,
    "expires_after_days": 30,
    "expires_after_days_inherited": true,
    "created_at": "2026-02-06T15:50:06.000000Z",
    "updated_at": "2026-02-06T15:50:06.000000Z",
    "deleted_at": null,
    "mode": "authoritative",
    "policy_rules_count": 1,
    "policy_users_count": 27,
    "policy_conditions_count": 1,
}
```

An imported attribute's ruleset starts in the `authoritative` mode, and the ruleset of an attribute can't be changed to another mode. Its 30-day grace period is inherited, which is why `expires_after_days_inherited` is `true`. [Inheriting and Overriding Grace Periods](https://docs.provisionr.io/concepts/control/qualification.md#inheriting-and-overriding-grace-periods) explains where an inherited grace period comes from.

Each imported ruleset includes one rule by default.

![A single rule with one condition for an attribute](https://mintcdn.com/provisionr/VNq5QTz41OqBybRj/images/diagrams/architecture/policy/intro/policy-intro-rule-01-simple-attribute.svg?fit=max\&auto=format\&n=VNq5QTz41OqBybRj\&q=85\&s=66524b123dd221bf08c6362abbacaaf0)

```json Policy Rule for IT Department Attribute highlight={5} theme={null}
{
    "id": "porul_01kgstavz1ckwq4jv3pcef3pwk",
    "policy_ruleset_id": "poset_01kgstavy0q6s4bkbsj08n25ts",
    "policy_role_id": "porol_01kgsszte9w7zj8at8zar2man8",
    "is_imported": true,
    "description": "Imported rule from integration profile attribute",
    "expires_after_days": 30,
    "priority": 88,
    "created_at": "2026-02-06T15:50:06.000000Z",
    "updated_at": "2026-02-06T15:50:06.000000Z",
    "activated_at": "2026-02-06T15:50:06.000000Z",
    "expires_at": null,
    "deleted_at": null,
    "state": "active",
    "policy_conditions_count": 1,
    "manifest_users_count": 27,
    "expires_after_days_inherited": true,
}
```

The imported rule is created with a single [Identity Condition](#identity-conditions), which matches the string value found in your users' profile data. For the `IT` attribute, that's a `department` that equals `IT`.

```json Policy Condition for IT Department Attribute Rule highlight={12-14} theme={null}
{
    "id": "pocon_01kgstavzzfnydfpjscr3c1t5z",
    "policy_ruleset_id": "poset_01kgstavy0q6s4bkbsj08n25ts",
    "policy_rule_id": "porul_01kgstavz1ckwq4jv3pcef3pwk",
    "directory_attribute_id": null,
    "manager_id": null,
    "integration_id": "okitg_01kgst0661n7j9natpk42xp12v",
    "directory_user_id": null,
    "is_imported": true,
    "type": "identity",
    "description": "User Demo identities where department equals IT",
    "profile_key": "department",
    "profile_operator": "equals",
    "profile_value": "IT",
    "created_at": "2026-02-06T15:50:06.000000Z",
    "updated_at": "2026-02-06T15:50:06.000000Z",
    "deleted_at": null,
}
```

This rule makes the attribute your single source of truth (SSOT) for who is in IT. You can attach the attribute to any group or resource, and since each of them refers to the attribute by its ID, a change to the attribute's value only needs to be made in one place. Every group and resource that uses the attribute follows that change, so you never have to rename the same string-matching rule in each of them.

## Policy Conditions

A Policy Ruleset can have an unlimited number of rules, and each rule can have an unlimited number of conditions, so you can build rulesets with as much granularity as you need.

A condition works like an equation. We evaluate the left side against the right side with an **operator**, and the result is either true, which means the user matches, or false, which means they don't.

If a user **matches every condition** in a rule, they are considered a **qualified user** for that rule. In other words, the conditions of a rule combine as *this **and** that*. A user who matched in the past but no longer matches is considered a **disqualified user**, and any user who doesn't match all of the conditions is ignored.

A user only needs to qualify for **any one of the rules** to be added as a [Policy User](#policy-user-lifecycle). In other words, the rules of a ruleset combine as *this **or** that*.

![A ruleset with multiple rules](https://mintcdn.com/provisionr/VNq5QTz41OqBybRj/images/diagrams/architecture/policy/intro/policy-intro-rule-04-multi-rule.svg?fit=max\&auto=format\&n=VNq5QTz41OqBybRj\&q=85\&s=bcab98da3487bd85b774790e09ad3428)

Rules combine with or, so a user who matches any rule qualifies.

There is no deny or except precedence between rules. Once a user qualifies through one rule, adding a second, more restrictive rule never removes them, because the new rule only brings in anyone new who matches it.

Multiple conditions are how a rule gets you closer to least privilege. Each condition narrows the set of users who qualify, which gives you finer granularity and avoids the sprawl of role-based access control strings.

![Typical ruleset with multiple rules and conditions](https://mintcdn.com/provisionr/VNq5QTz41OqBybRj/images/diagrams/architecture/intro/concepts/concepts-policy-ruleset.svg?fit=max\&auto=format\&n=VNq5QTz41OqBybRj\&q=85\&s=e62e84d78371842119f5441ddac8423e)

Typical ruleset with multiple rules and conditions

For example, take the imported `Sales` division. You can narrow it further with a custom `Sales Region` dimension, in which a `US Country Sales Team` attribute uses a single rule with two conditions, and a user must match both of them.

| Condition type | Matches |
| - | - |
| Identity | `division` equals `Sales` |
| Identity | `countryCode` equals `US` |

Each condition that you add to a rule tightens the result. A `California Sales Account Executives` attribute narrows the audience down to one team with four conditions, all of which must be true.

| Condition type | Matches |
| - | - |
| Identity | `division` equals `Sales` |
| Identity | `countryCode` equals `US` |
| Identity | `state` equals `CA` |
| Identity | `title` equals `Account Executive` |

There is no hard limit on the number of conditions in a rule, but in practice, a handful is enough to isolate almost any team.

![A sales team rule with several conditions](https://mintcdn.com/provisionr/VNq5QTz41OqBybRj/images/diagrams/architecture/policy/intro/policy-intro-rule-03-multi-sales.svg?fit=max\&auto=format\&n=VNq5QTz41OqBybRj\&q=85\&s=bb99c687926df828f21949d66a7983a0)

Each additional condition narrows a rule to a more precise audience.

### Identity Conditions

An Identity Condition matches users on the string values in their identity profile data for an integration, which is the profile that the vendor's API returns for each of them.

When you create an Identity Condition, you choose an existing integration and the key that you want to evaluate, such as `department`. Then you choose the operator to use, such as `equals`, and enter the string value that you're looking for, such as `IT`.

You've already seen how we import the profile data from the integration API and create dimensions and attributes from the keys and values in that profile data. Each of those imported rules uses an Identity Condition.

During each sync, Provisionr looks at every identity, which is a user's data from the chosen integration, and returns the users whose profile has the key with a value that satisfies the operator. In other words, a user matches when their value, compared with yours by the operator, evaluates as true. Only identities that are active or scheduled to expire are evaluated, so a deactivated identity never matches.

### Condition Operators

We support several condition operators for string evaluation. Most of them compare the user's profile value with the value in the condition, while `empty` and `exists` only check whether the profile has a value for the key at all. Every operator ignores case, so `it` and `IT` are treated as the same value.

| Operator | Matches when the profile value | Examples |
| - | - | - |
| `equals` | Is equal to the value | `department` equals `IT` |
| `not` | Is not equal to the value | `division` is not `Finance` |
| `empty` | Is null or an empty string | `title` is empty |
| `exists` | Is not null and not an empty string | `employeeNumber` exists |
| `greater` | Is greater than or equal to the value | `created_at` is greater than or equal to `2026-01-01` |
| `less` | Is less than or equal to the value | `expired_at` is less than or equal to `2025-12-31` |
| `prefix` | Starts with the value | `title` starts with `Senior`, `Sr.`, `VP`, or `Vice President` |
| `suffix` | Ends with the value | `email` ends with `@example.com`, `-admin@example.com`, or `@vendorcorp.com`, and `title` ends with `Manager` |
| `contains` | Contains the value as a keyword | `title` contains `Engineer` or `Manager` |

### Identity Condition Example

The typical ruleset shown in [Policy Conditions](#policy-conditions) includes a rule for the IT Applications team with an Identity Condition where `title` contains `IT Applications`. This means that any user whose job title includes the keyword "IT Applications" matches this condition, although they still have to match all of the rule's other conditions as well.

Ian Sanford's identity shows how this works. His title is `IT Applications Engineer`, so he matches the condition.

```json Directory Identity Data highlight={18} theme={null}
{
    "id": "dridt_01kgst84tp97hr59ed28cvn3yh",
    "integration_id": "okitg_01kgst0661n7j9natpk42xp12v",
    "directory_user_id": "drusr_01kgst84wc8ak0a5ng6snvtw1n",
    "vendor_id": "14d480e7",
    "email": "isanford@example.com",
    "profile": {
        "costCenter": "G&A",
        "department": "IT",
        "division": "Finance",
        "email": "isanford@example.com",
        "employeeNumber": "fcf70a5d",
        "firstName": "Ian",
        "handle": "isanford",
        "lastName": "Sanford",
        "managerId": "e31f9013",
        "reportsTo": "IT Applications Manager",
        "title": "IT Applications Engineer"
    },
    "provisioned_at": "2020-01-13T14:47:36.000000Z",
    "profile_changed_at": "2020-01-13T14:47:36.000000Z",
    "last_authenticated_at": "2026-01-28T14:46:36.000000Z",
    "deprovisioned_at": null,
    "created_at": "2026-02-06T15:48:36.000000Z",
    "updated_at": "2026-02-06T15:48:36.000000Z",
    "deleted_at": null,
    "state": "active"
}
```

### Considerations for String Matching

> [!TIP]
>
> Only use Identity Conditions for **partial** matches, such as `contains`. For exact `equals` matches, use an [Attribute Condition](#attribute-conditions), [Manager Condition](#manager-conditions), or [User Condition](#user-conditions) instead.

Identity string matching is a raw string evaluation with no lifecycle management. If the value is renamed in the integration, the condition silently stops matching, and neither your administrators nor your end users can see that it happened.

If you reuse the same logic in multiple places, or the value is predictable, use an [Attribute Condition](#attribute-conditions) instead. This gives you a single source of truth, and a menu of choices to select from rather than raw strings repeated in each rule.

> [!NOTE]
>
> Your policies are **mapped to the ID instead of the string value**, so if the value changes, you can update the attribute's display name and all of the policies that reference that attribute will automatically be updated.

Each attribute has its own lifecycle management, so you can track its changes over time and have a clear audit trail of what happened, when, and why. Attributes have successor and predecessor relationships, which lets us handle remappings as the names of your attributes change over time.

Renaming an attribute's display name or handle in Provisionr is always safe, because the relationships are tied to the ID. The case that the attribute lifecycle handles is a *different value arriving upstream*. When a value is renamed at the source, say from `Commercial Sales` to `Mid-Market Sales`, the next sync detects the new value and creates an attribute for it, while the old imported condition stops matching, because no user carries the old value anymore. Rather than silently dropping access, Provisionr surfaces the affected users for review and hands them to the deprecation lifecycle, which grants a [grace period](https://docs.provisionr.io/concepts/control/qualification.md#grace-periods) before any access is removed. That's enough time for a role change that needs a few days of overlapping access. [Creating New Policy Users](https://docs.provisionr.io/concepts/control/qualification.md#creating-new-policy-users) follows a rename like this one from start to finish. If you know about a rename ahead of time, you can avoid the new attribute altogether by [updating the existing attribute's `profile_value`](https://docs.provisionr.io/concepts/control/dimensions#attribute-lifecycle-changes).

You can also use `expires_at` to give an attribute an expiration date. Once the expiration date is reached, the attribute is automatically deprecated and no longer used in policies, and any users who were attached to it are automatically detached.

### Attribute Conditions

An Attribute Condition matches the users who hold a directory attribute. It's the most flexible condition type for defining rules based on user attributes, because the logic that decides who holds each attribute lives in a single source of truth.

Since each [Directory Attribute](https://docs.provisionr.io/concepts/control/dimensions.md#directory-attributes) has its own ruleset with rules and conditions, it acts as a reusable ruleset. You can define your [string matching](#considerations-for-string-matching) once, as a single source of truth for your organization's logic, and then reuse that attribute in the rules of different groups and resources without repeating your string-matching logic in each of them.

You've already seen how we import the profile data from the integration API and create dimensions and attributes from the keys and values in that profile data. Each of these attributes can now be used in any rule as an Attribute Condition.

A user matches an Attribute Condition while they're on the attribute's manifest, including while their grace period for the attribute counts down. [Attribute Condition Grace Periods](https://docs.provisionr.io/concepts/control/qualification.md#attribute-condition-grace-periods) explains how that grace period and the group's own grace period run one after the other.

You can also create custom Directory Dimensions and Attributes. Each of them has a ruleset that you can add rules and conditions to, and that you can reuse by attaching it to various groups and resources. This is useful for granular dimensions that are now available in your HRIS and that you want to use across multiple groups and resources.

For example, you could create a `Team` dimension with an attribute for each team in your organization, and then use those attributes in any rule for any group or resource.

Custom attributes are also useful for special projects, sales regions, or deciding who should have access to data about a specific customer. If you're used to creating a Google Group and adding everyone to it, you can use a Provisionr attribute instead, and then use that attribute in your group rulesets. This gives you a single source of truth for who should have access to that customer or project, and you can use the attribute across multiple groups and resources without having to manage the membership of a Google Group, Google Drive folder, Slack channel, and so on.

Since each attribute has a database record with its own ID, you select the attribute from a dropdown menu when you create a condition, rather than having to remember the exact string that you need to match.

### Manager Conditions

A Manager Condition lets you choose a manager, and every user who reports to that person matches it. Both the manager and the report need to be active or scheduled to expire, so a report who has left the organization stops matching.

A rule can mix condition types. Pairing a Manager Condition with an [Identity Condition](#identity-conditions) keeps only the reports who also match a profile field. A `NorCal Account Team` rule might combine the two.

| Condition type | Matches |
| - | - |
| Manager | Reports to Wren Odell |
| Identity | `title` equals `Account Executive` |

Without the Identity Condition, the rule includes everyone who reports to the manager, and with it, the team narrows to a single job title.

New hires who report to this manager are added automatically. If a user's manager changes, they no longer qualify for the rule. This is handled by the deprecation lifecycle, so their access to groups and resources expires after the ruleset's [grace period](https://docs.provisionr.io/concepts/control/qualification.md#grace-periods).

> [!TIP]
>
> Manager Conditions only include direct reports, not the manager themselves. If you want the manager to be included as well, create an additional rule for them, based either on the manager's job title, if it's unique to that person, or on a User Condition with their specific user ID.

### User Conditions

A User Condition names a single Directory User, whom you select from a dropdown list. It's meant for corner cases, where a user doesn't have one or more of the attributes that would qualify them for a rule.

> [!TIP]
>
> Use User Conditions for exceptions, not as your main way of granting access. If you use User Conditions extensively, you lose the benefit of job roles that come with predefined access, because you'll need to add rules for each user during onboarding and remove them if they change job roles. When you use Attribute and Manager Conditions instead, the logic is based on each user's profile attributes rather than, in essence, their email address.

## Policy User Lifecycle

A **Policy Ruleset** has a list of **Policy Users**, which is a many-to-many mapping to Directory Users. This list is recalculated on a recurring schedule, so new users who match the conditions are added, and users who no longer match are deprecated.

When a user is attached to a ruleset, the relationship is stored as a **Policy User**. Each Policy User is a single grant of access to one user by one rule. Keeping each relationship as a record of its own gives you lifecycle tracking, which provides valuable data for auditing.

| Field | What it records |
| - | - |
| `policy_rule_id` | Which rule granted their access. It never changes. |
| `activated_at` | When they qualified and the grant began |
| `deprecated_at` | When they stopped qualifying and their grace period began |
| `expires_at` | When their access is scheduled to end |
| `deleted_at` | When the grant ended and they were removed |
| `state` | The current state of the relationship |

A Policy User only moves forward, from `active` to `expiring` to `expired`, or to `deactivated` when its policy is deactivated. When a user qualifies again, or qualifies under a different rule, we create a new Policy User instead of reopening the old one, so a user's history in a ruleset is a list of grants, each with its own start and end.

[Qualification](https://docs.provisionr.io/concepts/control/qualification.md) explains how each sync qualifies users, when a new Policy User is created, and where each grace period comes from.

## Rule Priority

Each rule has a priority from 1 to 99. If you don't set one, a custom rule gets a priority of 42 and an imported attribute rule gets 88, and yes, both of those numbers are pop culture easter eggs.

A user may qualify for multiple rules, but their Policy User is associated with only one of them. The sync records the rule that qualifies the **most users**, not the rule with the lowest priority value, so priority doesn't change this choice today.

This is designed so that the rules that apply to entire departments explain most of a ruleset's membership, and the narrower rules for a team, a manager, or a named user are recorded only for the users who qualify through them alone. It makes the exceptions in a ruleset easy to see, keeps your rule sprawl to a minimum, and shows you which rules don't have any effect.

For example, if a user qualifies for Rule X, which matches 140 users, and Rule Y, which matches 9 users, their Policy User is associated with Rule X.

Rules are qualified during each scheduled sync, when you activate a rule, and on demand when you [sync a specific ruleset](https://docs.provisionr.io/cli/workspace/v1/policy-ruleset/sync.md).

If the user no longer qualifies for `Rule X` but still qualifies for `Rule Y`, a new Policy User with `Rule Y` is created on the same sync, and the `Rule X` Policy User is expired. The user never stopped qualifying, so there's no grace period and no gap, and unless the role associated with each rule is different, the user won't notice any disruption or change. The two records show when they qualified under each rule.

If the user no longer qualifies for any rule, their Policy User is deprecated and scheduled for expiration at the end of its [grace period](https://docs.provisionr.io/concepts/control/qualification.md#grace-periods). [Qualification](https://docs.provisionr.io/concepts/control/qualification.md#rule-priority) explains the choice of rule in more detail.

## Short-Term Access

When the conditions of a rule are only meant to apply for a short period of time, you can give the rule an expiration date by [deprecating](https://docs.provisionr.io/cli/workspace/v1/policy-rule/deprecate.md) it with an `expires_at` value. Once the expiration date has passed, the next sync expires and soft deletes the rule, and the users it qualified stop qualifying through it.

Those users lose their access along with the rule on that same sync, without a grace period, unless another rule grants it to them. [Temporary Access](https://docs.provisionr.io/concepts/control/qualification.md#temporary-access) shows this pattern for a single person's access window.

An expiration date is useful for temporary access, such as these cases:

* A contractor who only needs access for 90 days
* A special project
* Vacation coverage that only needs access for a few days or weeks
* An employee who has changed job roles and is supporting their old team for the next few weeks or months while they transition to the new role

Since the sync retires the rule for you, you don't need to remove the rule or its conditions by hand once the access is no longer needed, and there's no lingering access to clean up after the expiration date has passed.

The sync checks for expiration dates that have passed, so a rule expires at the first sync after its expiration date, not at the exact moment that the date is reached. This means that there's a delay between when the rule's expiration date arrives and when its users stop qualifying. The longest delay is the time between your workspace's syncs, which depends on your [sync frequency](https://docs.provisionr.io/concepts/control/sync.md#sync-change-window).

***

With rules and conditions in place, the next page looks at how each sync turns them into a list of people, and how each person's access is recorded. We call this qualification.

[Continue reading: Qualification →](https://docs.provisionr.io/concepts/control/qualification.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.