> ## 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.

# Qualification

> How every sync decides who qualifies for a policy, records each person's access as a Policy User that only moves forward, and uses grace periods so that changes in your directory don't turn into surprise outages.

Now that you know how rules and conditions are put together, the next question is what Provisionr does with them. During every sync, we take the rules of each policy, compare them with the latest profile data for everyone in your directory, and work out who should have access. We call this **qualification**.

Qualification is where the decisions are made. It doesn't add anyone to a group or remove anyone from an application on its own. Instead, it produces the list of people that each group, resource, or attribute should contain, and the rest of the sync uses that list to make changes in your connected systems. When you want to know why someone has access, or why they still have it after moving to another team, this is where you'll find the answer.

This page walks through qualification the way you'll need it as a systems engineer, in this order:

* The lists that qualification works with, and the order of its steps
* How each person's access is recorded
* How grace periods give people time through changes
* Where to look when a result surprises you

The last section covers the same ground for auditors and compliance engineers, using the language of controls and evidence.

> [!NOTE]
>
> This page builds on [Policies & Rules](https://docs.provisionr.io/concepts/control/policies.md). If rulesets, rules, and conditions are new to you, start there first.

***

## Qualification Lists

When you look at a policy in Provisionr, you'll find three different lists of people. They overlap, and it's easy to mix them up, but each one answers a different question, so it helps to know which one you're looking at.

The first is the list of **qualified users** for each rule. These are the people who match that rule's conditions right now, and the list is rebuilt on every sync. A person who matches three rules appears on three lists, because each list is about the rule rather than the person.

The second is the **manifest**, which is the policy's answer to who should have access. It combines the qualified users of every rule into a single list, with each person appearing once alongside the one rule that grants their access. The manifest is what the group sync compares with the members in your vendor, and it's also what other policies read when one of their rules uses an attribute.

The third is the list of **Policy Users**, which are the records behind the manifest. Each Policy User is a single grant of access. It names one person, one policy, and the one rule that grants their access, along with timestamps for when the grant began and when it ended. The manifest is made up of the Policy Users that haven't ended yet. The ones that have ended are kept, and together they become that person's access history for the policy.

There's also a fourth list that you'll use for change management. The **staged users** of a draft rule are the people it would match if you activated it. We calculate them on every sync so that you can preview a rule before it goes live, but a staged rule never grants access to anyone.

| List | The question it answers | Recalculated |
| - | - | - |
| Staged users | Who would this draft rule grant? | Every sync, for staged rules only |
| Qualified users | Who matches this rule today? | Every sync |
| Manifest | Who should this group, resource, or attribute contain? | Every sync |
| Policy Users | Who had access, under which rule, from when until when? | A record is added or moves forward whenever the manifest changes |

You can list the staged users, qualified users, and manifest users of any ruleset or rule with the workspace API. The [Policy Users list](https://docs.provisionr.io/cli/workspace/v1/policy-user/list.md) in the CLI shows the current Policy Users and, when you ask for them, the ones that have ended.

## Qualification Steps

Qualification runs for a ruleset during every [scheduled sync](https://docs.provisionr.io/concepts/control/sync.md), when you activate a rule in the ruleset, and whenever someone with permission [syncs the ruleset on demand](https://docs.provisionr.io/cli/workspace/v1/policy-ruleset/sync.md). Each time, it follows the same eight steps in the same order.

The order matters more than it might seem. Every step that adds or replaces a grant runs before any step that ends one, so a person who moves from one rule to another stays on the manifest the whole way through, without a gap between syncs or even between two steps of the same sync.

**1. Expired Rules**

A rule can have an expiration date, and once that date has passed, the rule stops granting access. The sync moves the rule to `expired` before it evaluates anything else, so that its people are measured against the rules that remain. This is how short-term access expires on schedule.

**2. Rule Qualification**

For every active rule, and for every deprecated rule that hasn't reached its expiration date yet, the sync finds each person who matches **all** of the rule's conditions and records them as the rule's qualified users. Staged rules are evaluated in the same pass, but their matches are recorded as staged users and don't grant anything.

**3. Ruleset Manifest**

The qualified users of every rule are combined into one list, with each person appearing once. When someone qualifies through more than one rule, the rule that qualifies the most people is recorded as the one that grants their access. [Rule Priority](#rule-priority) explains why.

**4. New Policy Users**

A person on the manifest who doesn't have a current Policy User gets a new one. It starts in the `active` state, names the rule that granted it, and records when the grant began in `activated_at`.

**5. Superseded Policy Users**

Sometimes a person's current Policy User no longer describes their grant, either because a different rule now grants their access, or because they were counting down a grace period and have qualified again. In both cases, the sync creates a new record for them and ends the old one. The new record is created first and the old one is ended second, so the person stays on the manifest throughout.

**6. Deactivated Policy Users**

A person whose rule was deactivated, and who doesn't qualify through another rule, is **deactivated** at once, without a grace period. This includes anyone who was already counting down a grace period under that rule.

**7. Deprecated Policy Users**

A person with an `active` Policy User who is no longer on the manifest is **deprecated**. Their record moves to `expiring`, `deprecated_at` records when this happened, and its `expires_at` is set to the end of their [grace period](#grace-periods), or to the rule's expiration date if that comes first. They keep their access until then, which means that a person whose rule has already expired moves through this step and the next one in the same sync.

**8. Expired Policy Users**

Every `expiring` Policy User whose `expires_at` has passed moves to `expired` and leaves the manifest. The record itself is kept, and its `deleted_at` shows when the sync ended it.

Qualification doesn't call any vendor APIs. Its job is to make the decision, and the stages that follow carry it out. For a directory attribute, the manifest *is* the attribute's membership, and other policies read it through [Attribute Conditions](https://docs.provisionr.io/concepts/control/policies.md#attribute-conditions). For a group or resource, the [group sync](https://docs.provisionr.io/concepts/control/sync.md#group-and-resource-sync) compares the manifest with the members in your vendor and writes the difference. With Okta, [policy incidents](https://docs.provisionr.io/integrations/okta/incidents) can also hold those writes for review. A policy incident never changes what qualification decided. It only decides whether the result is written right away or after someone has had a chance to look at it.

> [!TIP]
>
> Qualification keeps the access decision separate from the access change. The decision is made from documented rules and recorded as a Policy User that names its rule, and the change is written to the vendor by a separate stage with its own events. This allows an auditor to test the control (does the manifest match the policy?) independently of the vendor operation (did the vendor receive the change?).

## Condition Matching

As you saw in [Policy Conditions](https://docs.provisionr.io/concepts/control/policies.md#policy-conditions), the conditions within a rule combine with **and**, so a person has to match every one of them, and the rules within a ruleset combine with **or**, so a person only needs to qualify for one rule. When you're investigating someone's access, the more useful question is what exactly makes a person match a condition, and what makes them stop matching it.

| Condition | A person matches while | A person stops matching when |
| - | - | - |
| Identity | Their identity in the chosen integration is active or scheduled to expire, and its profile value satisfies the operator | The profile value changes upstream, or the identity is deactivated |
| Attribute | They are on the attribute's manifest, **including while their attribute grace period counts down** | Their Policy User for the attribute expires, or they leave the organization |
| Manager | They report directly to the named manager, and both of them are active or scheduled to expire | Their manager changes, or they leave the organization |
| User | They are the named person and remain in the directory | They leave the organization |

A rule with no conditions matches no one. We never read an empty rule as "everyone", so a rule that you haven't finished building can't grant access by accident.

### Attribute Condition Grace Periods

An attribute is a policy too, with its own manifest and its own grace period. When a group's rule uses an Attribute Condition, the group trusts the attribute's manifest, and that manifest still includes the people who are counting down their grace period for the attribute. In other words, the two grace periods run one after the other.

You can see this by following Ian Sanford, the IT Applications Engineer from [Policies & Rules](https://docs.provisionr.io/concepts/control/policies.md), as he moves from IT to the Security team. The `IT` attribute has a 30-day grace period. The `it-admins` Okta group grants access with a rule that uses the `IT` attribute, and the group has a 7-day grace period.

| When | What happens |
| - | - |
| Day 0 | The sync imports Ian's new department. He no longer matches the `IT` attribute's rule, so his Policy User for `IT` is deprecated with 30 days of grace. |
| Days 0 to 30 | Ian is still on the `IT` manifest, so the `it-admins` rule still matches him, and nothing changes for the group. |
| Day 30 | The first sync after his attribute grace period ends expires his `IT` Policy User. The `it-admins` rule stops matching him, and his group Policy User is deprecated with 7 days of grace. |
| Day 37 | The first sync after his group grace period ends expires his group Policy User, and the group sync removes him from the Okta group. |

This is by design. The `IT` attribute is the source of truth for who is in IT, and its grace period is part of that answer, so everything built on top of the attribute agrees with it. If a group needs to follow a move faster than the attribute it relies on, lower the grace period on the attribute or its dimension, and not only on the group.

Departures work differently, and their grace periods don't stack in this way. A person who leaves your organization drops out of every attribute's manifest at once, so any group rule that relies on those attributes stops matching them on the same sync. See [Removing Access for Leavers](#removing-access-for-leavers).

## Rule Priority

The manifest records exactly one rule for each person, so that every grant has a single reason you can point to. When someone qualifies through more than one rule, we record the rule that qualifies the **most people**.

For example, imagine an `engineering-all` Google Group with two rules. Rule A matches everyone whose department is `Engineering`, which is 140 people. Rule B matches everyone who reports to Wren Odell, which is 9 people. Six of them are in Engineering, and the other three are contractors in another department. The six people in Engineering are recorded under Rule A, and only the three contractors are recorded under Rule B.

This gives you a view where the broad rules that follow your org structure explain most of a group's membership, and each narrow rule explains only the people who need it. When you see a Policy User that was granted by an exception rule, you know that person qualifies only through that exception, which is exactly what a reviewer wants to see.

> [!NOTE]
>
> Each rule also has a `priority` value, which [Policies & Rules](https://docs.provisionr.io/concepts/control/policies.md#rule-priority) describes. Today, the sync doesn't use priority to choose a person's rule. The number of people each rule qualifies is what decides.

Since the choice follows the size of each rule, it can change as rules grow or shrink. If a team rule ever qualifies more people than the department rule it overlaps with, the people who match both move to the team rule on the next sync, and each of them gets a new Policy User under it. Their access doesn't change unless the two rules grant different roles.

## Policy User Record

A Policy User is a small record, and each of its fields has a specific job.

```json Policy User for Ian Sanford in the IT Attribute theme={null}
{
    "id": "pousr_01kgstb2h7d9q4m1x8c5r3v6tn",
    "policy_ruleset_id": "poset_01kgstavy0q6s4bkbsj08n25ts",
    "policy_rule_id": "porul_01kgstavz1ckwq4jv3pcef3pwk",
    "directory_user_id": "drusr_01kgst84wc8ak0a5ng6snvtw1n",
    "created_at": "2026-02-06T15:50:07.000000Z",
    "updated_at": "2026-02-06T15:50:07.000000Z",
    "activated_at": "2026-02-06T15:50:07.000000Z",
    "deprecated_at": null,
    "expires_at": null,
    "deleted_at": null,
    "state": "active"
}
```

| Field | What it records |
| - | - |
| `policy_rule_id` | The rule that grants this access. It never changes, so if a different rule grants the access, that is a different record. |
| `activated_at` | When the person qualified and the grant began. |
| `deprecated_at` | When the person stopped qualifying and their grace period began. It is empty while they still qualify, even when the rule that grants them is expiring. |
| `expires_at` | When the grant is scheduled to expire, or when it expired. [Policy User Dates](#policy-user-dates) shows its value in each situation. |
| `deleted_at` | When the sync ended the grant and removed it from the manifest. Ended records are kept. |
| `state` | Where the grant is in its lifecycle. |

When you're investigating, it helps to keep `expires_at` and `deleted_at` apart in your mind. `expires_at` is when the grant was *due* to end, and `deleted_at` is when a sync actually *ended* it, which is the first sync after the due time.

### Policy User States

| State | Meaning | Can move to |
| - | - | - |
| `active` | A current grant. | `expiring` when deprecated, `expired` when superseded, or `deactivated` when the rule or policy is deactivated |
| `expiring` | The person stopped qualifying and is counting down a grace period. They are still on the manifest and still have access. | `expired`, when the grace period ends or the record is superseded, or `deactivated` when the rule or policy is deactivated |
| `expired` | The grant ended, either at the end of a grace period or because a new record replaced it. | Nothing, because the record is now history |
| `deactivated` | The grant ended without a grace period because its rule or policy was deactivated. | Nothing, because the record is now history |

A record never moves backward. An `expiring` record is never made `active` again, and a record that has ended is never reopened. When a person qualifies again, their history gains a new record instead of an edited one.

It may help to think of a Policy User as one assignment in an employee's job history. If someone leaves the Sales team and rejoins it a year later, their HR record shows two Sales assignments with two start dates, not one assignment with its end date erased. Policy Users work the same way. Each record describes one continuous grant, and it stays true to what happened even after circumstances change.

> [!TIP]
>
> Because records only move forward, the system that produced the access history cannot revise it. A Policy User's rule, start, and end are written once, and later events add new records instead of changing existing ones. Point-in-time membership can therefore be reconstructed from the records themselves, and every transition is corroborated by an event in the [event log](https://docs.provisionr.io/concepts/workspace/logs.md), whose records cannot be edited.

### Policy User Lifecycle

Every Policy User moves through the same three phases, and this diagram follows one from start to finish. Qualification creates the record and keeps it `active` for as long as the person qualifies. Deprecation gives them a grace period when they stop qualifying, and expiration ends the grant and removes them from the manifest.

```mermaid theme={null}
flowchart TB
    subgraph Qualification
        matches["Person matches every condition of a rule"]
        active["Policy User is active"]
        check{"Still qualifies at the next sync?"}
    end

    subgraph Deprecation
        expiring["Policy User is expiring<br/>Grace period counts down and access continues"]
    end

    subgraph Expiration
        expired["Policy User is expired<br/>Person leaves the manifest"]
        deactivated["Policy User is deactivated<br/>Person leaves the manifest"]
    end

    matches --> active
    active --> check
    check -- "Yes" --> active
    check -- "No, they stopped matching" --> expiring
    check -- "No, the rule expired" --> expired
    check -- "No, the rule or policy was deactivated" --> deactivated
    expiring -- "Qualifies again, on a new record" --> active
    expiring -- "Grace period ends" --> expired
    expiring -- "Rule or policy deactivated" --> deactivated
```

A person only skips the grace period when the reason comes from the rule or the policy rather than from the person. When the rule that granted them expires, they go out with it on the next sync. When that rule is deactivated, they're deactivated on the sync that follows, and when the whole policy is deactivated, everyone is deactivated at once. A person who qualifies through another rule of the same policy keeps their access when one rule ends, and they receive a new record under that rule, which [Creating New Policy Users](#creating-new-policy-users) covers in detail.

### Policy User Dates

A Policy User has three dates that describe how a grant ends, and reading them together tells you which situation a person is in. `deprecated_at` is when they stopped qualifying, `expires_at` is when their access is due to end, and `deleted_at` is when a sync actually ended it. This table shows what the first two contain in each situation.

| Situation | State | `deprecated_at` | `expires_at` |
| - | - | - | - |
| Still qualifies, and the rule has no expiration date | `active` | Empty | Empty |
| Still qualifies, and the rule is expiring | `active` | Empty | The rule's expiration date, inherited from the rule |
| Stopped qualifying | `expiring` | When they stopped qualifying | The end of their grace period, or the rule's expiration date if that comes first |
| Grace period ended | `expired` | Unchanged | Unchanged |
| Went out with an expired rule | `expired` | The same as `expires_at`, because there was no grace period | The rule's expiration date |
| Replaced by a new record | `expired` | Unchanged | The time of the change, or the time their grace period ended if that had already passed |
| Rule or policy deactivated | `deactivated` | Unchanged | Empty, and `deleted_at` shows when the grant ended |

An empty `deprecated_at` tells you that the person never stopped qualifying during this grant, even when `expires_at` has a date, because that date belongs to the rule. Once both are set, the time between them is the grace period that the person actually received.

## Creating New Policy Users

The guiding principle is one record for each continuous grant under one rule. Anything that ends the grant, or changes the rule that grants it, starts a new record.

| Situation | Result |
| - | - |
| A person qualifies for the first time | A new `active` record |
| A person keeps qualifying under the same rule | Nothing changes, and the record continues |
| A person stops qualifying | The same record moves to `expiring`, and their grace period starts |
| A person qualifies again while counting down, such as after moving and moving back, or after a mistake is fixed during the grace period | A new `active` record, and the old record ends at this sync. Their access never drops. |
| A person qualifies again after their grace period ended, but before a sync removed the old record | A new `active` record in the same sync. The old record keeps the time its grace period ended. |
| A person qualifies again after their old record was removed | A new `active` record |
| A different rule now grants the person, because they moved teams, a rule was replaced by a new version, or rule sizes shifted | A new `active` record under the new rule. The old record ends at this sync without a grace period, because the person never stopped qualifying. |
| The rule that granted the person expires, and no other rule grants them | The record ends as of the rule's expiration date, without a grace period |
| The rule that granted the person is deactivated, and no other rule grants them | The record moves to `deactivated` on the sync that follows, without a grace period |
| The policy is deactivated | Every current record moves to `deactivated` at once, without a grace period |

Grace periods are there to absorb this kind of change without disrupting anyone. Suppose your IdP renames the `Commercial Sales` department to `Mid-Market Sales`. When the IdP starts sending the new name, the identity condition for the `Commercial Sales` attribute stops matching, and everyone who relied on it is deprecated. Nobody's access changes yet, because each of them is counting down a grace period. An administrator attaches the new attribute to the affected rules with a new rule version, the next sync qualifies everyone again, and each person receives a new record under the new rule.

Nobody lost access along the way, and the history shows exactly what happened. Each person's grant under the old rule ended on the day of the fix, and their grant under the new rule began at the same sync. [Considerations for String Matching](https://docs.provisionr.io/concepts/control/policies.md#considerations-for-string-matching) explains how attributes make renames like this easier to absorb.

## Grace Periods

Directory data changes all the time, and not every change means that someone's job has changed. Departments get renamed, a manager can change twice in the same week during a reorganization, an HRIS import can fail halfway through, and an administrator might fix a typo in a rule the day after activating it. If every one of these changes took effect immediately, each of them would remove access from people in the middle of their work.

A **grace period** is the number of days that a person keeps their access after they stop qualifying. Another way to think about it is that it turns a removal into a scheduled removal. During that time the person still has access, the change is visible to your administrators, and anything that turns out to be a mistake can be fixed before anyone notices.

### Inheriting and Overriding Grace Periods

You can set a grace period, in days, at several levels, and a level that doesn't set its own inherits one from the level above it. When a person is deprecated, the first level that sets a value is the one that applies.

| Level | Applies to | When not set |
| - | - | - |
| Rule | The people that this rule grants | Inherits from the ruleset |
| Ruleset | Every rule in the policy that doesn't set its own | Inherits from the dimension or integration |
| Dimension | The rulesets of every attribute in the dimension | Inherits the Provisionr default |
| Integration | The rulesets of every group from that integration | Inherits the Provisionr default |
| Provisionr default | Everything that doesn't set its own | 30 days for directory attributes, and 7 days for Okta groups and Google Workspace groups |

Each level reports two values so that you can see where its grace period comes from. `expires_after_days` is the grace period that applies after inheritance, and `expires_after_days_inherited` is `true` when that value comes from a level above. This makes it easy for you, or a reviewer, to tell which policies follow a default and which ones were tuned on purpose.

To override the grace period at a level, give it an `expires_after_days` value from `0` to `1095` days. To go back to inheriting, send `expires_after_days_inherited: true`, which clears the override. An empty value is rejected rather than treated as "inherit", so an update that leaves the field blank, or a tool that sends empty fields, can't clear an override by accident.

Inheritance is evaluated live, which means that a level that inherits doesn't store a number of its own. When you change a parent, the grace period changes for every level beneath it that inherits. For example, if you shorten a dimension's grace period from 30 days to 14, every attribute ruleset and rule in that dimension that hasn't set its own grace period now uses 14 days as well.

### Removing Access Immediately

A grace period of `0` removes access on the same sync that finds the person no longer qualifies. This is a good fit for privileged access, such as production administration, finance approvals, and security tooling, where an extra week of access after someone moves teams is more of a risk than a courtesy.

### Grace Periods and Expiring Rules

A grace period protects a person whose own details changed. It doesn't apply when the rule itself is ending, because the rule's expiration date has already given everyone notice, so a person's access never outlives the rule that granted it. If someone stops qualifying while their rule is expiring, they keep the shorter of their grace period and the time the rule has left. When the rule reaches its expiration date, the next sync ends the access of everyone it granted, as of that date and without a second grace period, unless another rule of the same policy grants them access.

The same limit applies to anyone who is already counting down when a rule is deprecated. If their grace period would end after the rule does, we bring their `expires_at` forward to the rule's expiration date, and each of those people gets a `policy.user.grace.shortened` event that shows the old and new dates. The rule's `policy.rule.deprecate.success` event records how many people were affected in `metadata.expiring_users_shortened`.

An attribute limits a grace period in the same way, because everyone on an attribute's policy goes with it when it expires. If someone stops qualifying while their attribute is expiring, they keep the shorter of their grace period and the time the attribute has left, and deprecating an attribute brings forward any grace period that would end after it does, with the same event for each person.

### Grace Period Timing

The clock starts at the sync that detects the change, not at the moment the change was made in your HRIS or IdP. For example, if your workspace syncs daily at 02:00 and someone's department is changed at 09:00, their grace period starts at 02:00 the next morning.

In the same way, the clock stops at the first sync after `expires_at`. With a 7-day grace period and a daily sync, a person loses access between 7 and 8 days after the sync that deprecated them. The [sync frequency](https://docs.provisionr.io/concepts/control/sync.md#sync-change-window) of your workspace sets that precision.

A grace period is also fixed at the moment it starts. If you change a grace period at any level, the change applies to the next person who is deprecated, and not to anyone who is already counting down, because their `expires_at` was set when they were deprecated. The only thing that can change it afterward is their rule or attribute being deprecated, which [Grace Periods and Expiring Rules](#grace-periods-and-expiring-rules) explains.

Putting it all together, the time between a change in your source system and the removal of access is the wait for the next sync, plus the grace period, plus the grace periods of any attributes that the rule depends on, plus the wait for the first sync after the grace period ends.

## Changing Rules

A live rule is never edited in place. Its conditions are locked when it's activated, so to change a rule, you [duplicate it into a new version](https://docs.provisionr.io/integrations/okta/rollback#rule-versions), edit the staged draft, and activate the draft. Each rule action has a predictable effect on the people that the rule grants.

| Rule action | Effect on people |
| - | - |
| Activate a staged rule | Activation starts a sync of the policy, and the rule's matches qualify. People who already qualify through another rule move to the new rule only if it is now the larger rule. |
| Activate a new version and retire the old one | People move to the new version, and each of them receives a new record. Nobody's access is interrupted. |
| Deprecate a rule | The rule keeps granting until its expiration date, and its people lose their access along with it unless another rule grants it to them. A rule deprecated without an explicit expiration date is given one from the ruleset's grace period, and that is the only grace period its people receive. |
| Deactivate a rule | The rule stops granting at once, and the sync that follows deactivates everyone it granted, without a grace period, unless another rule grants them access. |
| Deactivate the ruleset | Every Policy User of the policy is deactivated at once, without a grace period. |

The difference between deprecating and deactivating a rule is worth remembering. Deprecating a rule means that it expires on a date, so people keep their access until that date. Deactivating a rule means that it stops granting now, so people lose their access on the sync that follows.

### Temporary Access

Some access is only meant to last for a short time. An on-call engineer might need production database access for a four-hour incident, or a contractor might need a shared drive for the three days of an engagement, and neither of them should still have that access next month because someone forgot to remove it.

You can grant time-boxed access with a rule that has a User Condition naming the person and an expiration date. When the expiration date passes, the next sync retires the rule, and the person's access ends along with it on that same sync, whatever grace period the rule has.

Since each window is its own rule, each window also gets its own Policy User record, with its own start and its own end. If the same person needs access again next month, that's a second rule and a second record rather than an extension of the first. This allows access reviews to see each grant separately, with its own justification, which is how temporary access should be reviewed. [Short-Term Access](https://docs.provisionr.io/concepts/control/policies.md#short-term-access) covers more ways to use rule expiration dates.

The precision follows your sync schedule. A window that ends at 14:00 in a workspace that syncs every three hours ends at the first sync after 14:00.

## Removing Access for Leavers

A grace period is meant to protect people whose attributes changed, not people who have left your organization. When someone leaves, your IdP deactivates their account, and the scheduled sync takes care of everything after that, in this order.

**1. Directory User Deactivation**

The user sync, which runs before qualification in every scheduled sync, imports the deactivation and marks the Directory User as deactivated.

**2. No Matching Conditions**

During qualification, the person no longer matches any conditions. Identity conditions don't match because their identity is deactivated, Attribute Conditions don't match because they've left every attribute's manifest, and the manager conditions and User Conditions that name them don't match either.

**3. Policy User Deprecation**

Every policy that granted them access deprecates their Policy User. The record counts down that policy's grace period like any other, so it shows when the grant would have ended if they had moved to another team instead.

**4. Group Removal**

Group write-back never wants a person who has left, whatever their grace period. The same sync removes them from every group that a policy manages and records the reason as `departed`. See [Okta Groups](https://docs.provisionr.io/integrations/okta/groups.md#wanted-members).

The same is true of anything built on an attribute. Attributes aren't written to a vendor, and a person who has left is no longer counted on any attribute's manifest, so every rule that uses an Attribute Condition stops matching them on the same sync.

> [!NOTE]
>
> For a person who has left, the Policy User's `expires_at` is when the grant would have ended for someone who moved teams, not when their access ended. The evidence that their access was removed is the write-back event with the reason `departed`.

## Qualification Troubleshooting

When a result surprises you, these are the tools you'll reach for, roughly in the order you'll need them.

Before you activate a rule, you can preview it. A staged rule's staged users show exactly who it will grant, and comparing them with the current rule's qualified users shows you who will gain access and who will lose it before anything changes.

To look at a person's grant, start with the [Policy Users list](https://docs.provisionr.io/cli/workspace/v1/policy-user/list.md), which you can filter by ruleset, rule, or person, and which can include the records that have ended. [Describing a Policy User](https://docs.provisionr.io/cli/workspace/v1/policy-user/describe.md) shows its rule, its timestamps, and links to its event logs.

The event log tells the rest of the story. Every time a record changes state, we write an event that names the record, the person, the rule, and the policy, and the create and deprecate events also list the rule's conditions in plain language. See [Logging Qualification](#logging-qualification).

If you don't want to wait for the next scheduled sync, you can [sync a ruleset on demand](https://docs.provisionr.io/cli/workspace/v1/policy-ruleset/sync.md) to run qualification for that policy right away, which is useful after a rule change during a change window. Each on-demand sync is recorded as `policy.ruleset.sync.initiated.api`.

> [accordion] Missing Access
>
> Start by checking that the rule is active rather than staged. Then check that the person matches **every** condition of the rule and not just most of them, that their identity is active in the integration that each identity condition names, and that they're on the manifest of every attribute that the rule uses. Finally, check whether a sync has run since the change. Keep in mind that a rule with no conditions grants access to no one.

> [accordion] Access Kept After a Move
>
> They're almost certainly counting down a grace period. Their Policy User will be `expiring`, and its `expires_at`, along with the `policy.user.deprecate.success` event, shows when their access ends. If the rule uses an Attribute Condition, the attribute's grace period runs first. See [Attribute Condition Grace Periods](#attribute-condition-grace-periods).

> [accordion] Multiple Policy User Records
>
> That's their history. Each record is one continuous grant under one rule, so when you read them in order of `activated_at`, you'll see each time they moved between rules, moved to a new rule version, or qualified again after a grace period.

> [accordion] Record Changes Without Access Changes
>
> This usually means that a rule was replaced by a new version, or that a rule grew larger than a rule it overlaps with, so people moved to a different rule. Each of them received a new record, the old records ended at the same sync, and their access was continuous throughout.

> [accordion] Unexpected Granting Rule
>
> When a person qualifies through more than one rule, the rule that qualifies the most people is the one recorded, and priority doesn't affect this choice. See [Rule Priority](#rule-priority).

***

## Audit and Compliance Reference

This section describes qualification in terms of controls and evidence. Everything here is produced by Provisionr on every sync, so none of it needs to be collected by hand.

### Control Objectives

Qualification shows that access is derived from policy rather than granted by hand. The membership of every managed group, resource, and attribute is computed from documented rules on every sync, and each person's record names the rule that qualifies them.

It also shows that role changes are acted on without anyone having to ask. When a person no longer meets a rule's conditions, their access is deprecated at the next sync and removed after a defined, configured grace period, without a ticket, a reviewer, or a reminder.

Exceptions are explicit and attributable. Access for a named individual requires a rule with a User Condition, and since the broadest qualifying rule is recorded for each person, a grant recorded under an exception rule identifies someone whose only access is through that exception.

Policy changes are controlled as well. A live rule cannot be edited, so changes are made as new rule versions that are staged, previewed, and activated, and each step is recorded along with the person or service account that performed it.

### Mapping Controls to Evidence

Qualification supports the controls below. It is one part of the control environment, and the identity lifecycle in the IdP, write-back to vendors, and administrative access to Provisionr are each covered on their own pages.

| Framework | Control | How qualification supports it | Evidence |
| - | - | - | - |
| SOC 2 | CC6.1 Logical access security | Access to managed groups and resources follows documented rules evaluated on every sync | Rules and conditions, the manifest, and Policy User records |
| SOC 2 | CC6.2 Registration and authorization | Access is granted only to people who meet the conditions of an activated rule | `policy.rule.activate.success` with its actor, and `policy.user.create.success` with the matching conditions |
| SOC 2 | CC6.3 Modification and removal of access | Movers are deprecated automatically and removed after a configured grace period, and leavers are removed from groups on the sync that imports their departure | `policy.user.deprecate.success` with `expires_at`, `policy.user.expired.deleted`, and the write-back removal events with the reason `departed` |
| SOC 2 | CC8.1 Change management | Rules are versioned, previewed as staged users, and activated as recorded changes | `policy.rule.duplicate.success`, `policy.rule.activate.success`, and `policy.rule.deactivate.success` |
| ISO/IEC 27001:2022 | A.5.15 Access control and A.5.18 Access rights | Access rights are provisioned, adjusted, and removed by rules tied to role attributes | Policy User history for each person and each policy |
| ISO/IEC 27001:2022 | A.8.2 Privileged access rights | Privileged policies can remove access on the sync that detects a change, with a grace period of zero, and exceptions require named rules | Grace period settings, and rules with User Conditions |
| NIST SP 800-53 Rev. 5 | AC-2 Account management, including AC-2(2) for temporary access | Group and resource memberships are created, changed, and removed automatically, and time-boxed rules end on a set date | Policy User records and `policy.rule.expired.delete.success` |
| NIST SP 800-53 Rev. 5 | AC-6 Least privilege | Rules require every condition to match, and narrow rules are recorded only for the people who need them | Rules and conditions, and the qualified users of each rule |
| SOX ITGC | Logical access for provisioning, transfers, and terminations | The lifecycle of each grant is recorded with its start, its scheduled expiration, and the time it actually ended | Policy User records and their events |

### Preserving Access History

Policy User records only move forward, from active to expiring, and then to expired or deactivated, and never back. Qualifying again creates a new record instead of reopening an old one, so no transition erases an earlier one. The granting rule cannot change on a record either. A change of rule ends one record and starts another, each with its own timestamps.

Ended records are retained. They are soft deleted rather than removed, and they can be listed and filtered by when they ended. When one record replaces another, the new record is created before the old one ends, so the two overlap rather than leave a gap, and continuous access always reads as continuous.

Every transition also writes an event to the workspace event log. Event records cannot be edited or permanently deleted, and a soft delete of an event is itself recorded as a new event. See [Event Logs](https://docs.provisionr.io/concepts/workspace/logs.md).

Decisions are made by the system, and policy changes are attributed to the people who made them. Qualification events record the actor that started the sync, which is the system for a scheduled sync, or the person or service account that started an on-demand sync. Rule and ruleset changes record the person or service account that made them.

### Logging Qualification

All of these events are stored in the workspace event log, at the `info` level unless noted. Each Policy User event names the Policy User as the record, the Directory User as the subject, the granting rule as the related record, and the attribute, group, or resource that the policy belongs to as the parent.

| Event | Recorded when | What to look for |
| - | - | - |
| `policy.user.create.success` | A person qualifies and a new grant begins | `metadata.conditions`, which lists every condition of the granting rule in plain language |
| `policy.user.update.success` | A grant is superseded by a new record. Two events are written, one for the old record and one for the new. | `attribute_value_old` and `attribute_value_new` hold the old and new rule. When they are the same, the person qualified again under the same rule during or just after a grace period. `metadata` links the old and new records. |
| `policy.user.deprecate.success` | A person stops qualifying and their grace period starts | `metadata.expires_at` and `metadata.days_until_expiration`, `metadata.conditions`, which lists the conditions they no longer meet, and `metadata.expires_with_rule` and `metadata.expires_with_attribute`, which are `true` when the rule's or attribute's expiration date set the end of access instead of the grace period |
| `policy.user.grace.shortened` | A rule's or attribute's expiration date cuts a person's grace period short | `attribute_value_old` and `attribute_value_new`, which hold the old and new `expires_at`, `metadata.reason`, which says whether a rule or an attribute caused it, with the person as the subject and the rule as the related record |
| `policy.user.expired.deleted` | A grace period ends and the grant leaves the manifest | `metadata.expires_at`, when it was due, and `metadata.deleted_at`, when it ended |
| `policy.user.deactivate.success` | A grant ends without a grace period because its rule or policy was deactivated | The `policy.rule.deactivate.success` event of the rule, or the `policy.ruleset.deactivate.success` event of the policy |
| `policy.rule.duplicate.success` | A new version of a rule is drafted | The actor. The new draft is the record, and the version it came from is the parent. |
| `policy.rule.activate.success` | A rule version goes live | The actor |
| `policy.rule.deprecate.success` | A rule is given an expiration date | `metadata.expires_at`, and `metadata.expiring_users_shortened`, which is the number of people whose grace period now ends with the rule |
| `policy.rule.deactivate.success` | A rule stops granting at once | The actor |
| `policy.rule.expired.delete.success` | A rule reaches its expiration date and stops granting | `metadata.users_count`, the number of people it qualified when it ended |
| `policy.ruleset.sync.initiated.api` (debug) | Someone runs qualification for a policy on demand | The actor |

Progress summaries for each sync are written to operational logs rather than the event log, so the per-person events above are the evidence of record. The events for changes written to Okta, including changes held for review, are listed in [Okta Audit Events](https://docs.provisionr.io/integrations/okta/audit-events).

When a person stops qualifying, the deprecation event records the conditions they no longer meet and when their access ends.

```json policy.user.deprecate.success theme={null}
{
    "event_type": "policy.user.deprecate.success",
    "level": "info",
    "message": "Policy User no longer matches Policy Conditions and is scheduled for expiration",
    "record_type": "policy_user",
    "record_id": "pousr_01kgstb2h7d9q4m1x8c5r3v6tn",
    "parent_type": "directory_attribute",
    "parent_id": "dratr_01kgstavxctryyfg46k2dnepqc",
    "related_type": "policy_rule",
    "related_id": "porul_01kgstavz1ckwq4jv3pcef3pwk",
    "subject_type": "directory_user",
    "subject_id": "drusr_01kgst84wc8ak0a5ng6snvtw1n",
    "metadata": {
        "conditions": {
            "pocon_01kgstavzzfnydfpjscr3c1t5z": "User Demo identities where department equals IT"
        },
        "days_until_expiration": 30,
        "expires_at": "2026-12-08T02:04:11Z",
        "expires_with_rule": false
    }
}
```

When a grant is superseded, the event on the old record names both rules and both records. In this example, the `it-admins` group's rule was replaced by a new version, and Ian moved to it at the same sync.

```json policy.user.update.success (old record) theme={null}
{
    "event_type": "policy.user.update.success",
    "level": "info",
    "message": "Policy User Superseded by a New Record",
    "record_type": "policy_user",
    "record_id": "pousr_01kgt0c4m8r2v6x9z3b7d5f1hj",
    "attribute_key": "policy_rule_id",
    "attribute_value_old": "porul_01kgt0bw5n9q3s7v1x4z8c2e6g",
    "attribute_value_new": "porul_01kj9w3m5t8x2b6c4e7g1h0q3r",
    "parent_type": "okta_group",
    "parent_id": "okgrp_01kgsszt7m4n8q2r6v9w3x5ybc",
    "related_type": "policy_rule",
    "related_id": "porul_01kgt0bw5n9q3s7v1x4z8c2e6g",
    "subject_type": "directory_user",
    "subject_id": "drusr_01kgst84wc8ak0a5ng6snvtw1n",
    "metadata": {
        "old_policy_user_id": "pousr_01kgt0c4m8r2v6x9z3b7d5f1hj",
        "new_policy_user_id": "pousr_01kj9w3p2v6y8d1f5h3k7m9n2q"
    }
}
```

The matching event on the new record has the new Policy User as its record and the new rule as its related record.

### Common Audit Questions

To show who had access to a group on a given date, list the policy's Policy Users, including the ones that have ended. A person had access on that date if their record's `activated_at` is on or before the date and its `deleted_at` is empty or after it. A person whose record was `expiring` on that date still had access. The group sync's events then show when the vendor received each change.

To explain why a person has access, start with their current Policy User, which names the rule. The `policy.user.create.success` event lists the conditions that qualified them, and the rule's `policy.rule.activate.success` event names who activated it. [Reconstructing Why Someone Has Access](https://docs.provisionr.io/integrations/okta/audit-events#reconstructing-why-someone-has-access) follows the same trail backward from an Okta membership change.

To show how quickly access was removed after a termination, start with the `directory.user.deactivate.success` event. The write-back removal events from the same sync, with the reason `departed`, show the person leaving each group. A termination shouldn't wait for a grace period, so a removal that came later than the sync which imported the departure is worth investigating.

To show how quickly access was removed after a transfer, look at the `policy.user.deprecate.success` events, which show when each policy scheduled the end of access, and the `policy.user.expired.deleted` events, which show when each grant ended. Each interval should equal the configured grace period plus at most one sync interval, unless the rule's own expiration date ended it sooner, and any attribute grace periods that a group rule depends on run first.

To find access that is granted by exception, list the rules that have User Conditions, along with their qualified users. The Policy Users recorded under those rules are the people whose access exists only by exception. People who match both an exception rule and a broader rule are recorded under the broader rule, so when you're assessing whether an exception is still justified, review the exception rule's qualified users and not only the manifest.

To check whether access was interrupted during a transfer, compare the end of the old record with the `activated_at` of the new one. A superseded record ends at the same sync that starts its successor, and the successor is always created first.

### Reviewing Qualification Settings

When you review a workspace, these are the settings that shape qualification.

* The grace period at every level, and which policies inherit a default. Policies that grant privileged access should use `0`, or have a documented reason not to.
* The rules with User Conditions, and the business justification in each rule's description.
* The rules with expiration dates, which represent time-boxed or deprecated grants.
* The rule history for the review period, including the versions that were drafted, activated, and retired.
* The sync frequency, which sets how quickly a change in the source system is acted on.

### Known Limitations

Qualification runs on the sync schedule, so it acts on a change at the next sync rather than in real time. The workspace's plan sets how often that is.

A Policy User's expiration date is not evidence of when a termination took effect. A departed person's Policy User counts down its grace period just like a mover's, but their group memberships are removed on the sync that imports the departure, so use the write-back events rather than the Policy User's `expires_at` to evidence the timing of a termination.

For moves, an attribute's grace period runs before the grace period of any group that uses it. See [Attribute Condition Grace Periods](#attribute-condition-grace-periods).

Keep in mind that qualification makes the decision and write-back carries it out. The manifest is the authoritative statement of who should have access, and whether a vendor reflects it depends on the group sync and, for Okta, on any changes that are held for review.

***

With qualification in place, every policy has a list of the people it grants and a record of how each of them got there. The next page looks at the groups and resources that those lists are written to.

[Continue reading: Groups & Resources →](https://docs.provisionr.io/concepts/control/groups.md)


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