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

# Dimensions & Attributes

> Profile metadata becomes Dimensions (keys) and Attributes (values), stored as relational records so policy rules match stable IDs instead of brittle strings.

Now that you know how each person becomes a Directory User with an identity in each of your integrations, you can take a closer look at the profile data that comes with those identities. You're probably already familiar with this user profile metadata, because it's stored in your Identity Provider (IdP) and your other systems, and it's the data that we use to decide which people should have access to which groups and resources.

Here's the identity of Ian Sanford, the IT Applications Engineer who appears throughout these pages, with his profile data highlighted.

```json Directory Identity for Ian Sanford highlight={8-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"
}
```

The profile is made up of keys and values. Each key, such as `department`, becomes a dimension, and each distinct value of that key, such as `IT`, can become an attribute of the dimension. The rest of this page explains how we create and maintain those records, and why your policies match them instead of the raw text.

## Directory Dimensions

The profile keys are the **Dimensions**, such as department, division, cost center, and job title.

We automatically create a Dimension record for each unique key that appears in any of the user profiles in your integration's API response. In Okta, for example, this includes all of the [standard attributes](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/getUser) and any [custom profile attributes](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-add-custom-user-attributes.htm) that your organization uses.

These keys include business contact information, such as `name`, `email`, `phone number`, and `status`, and organization data, such as `title`, `department`, `division`, and `cost center`. For data safety, we don't import postal address information at the street or postal code level. We do import the city, the province or state, and the country code, because some systems, such as HR benefits applications, depend on where each person lives. [How the Okta Sync Works](https://docs.provisionr.io/integrations/okta/sync.md) describes how the Okta integration discards home address fields before anything is stored.

Each dimension has a `name` for display and a `handle`, which is a short, lowercase abbreviation, such as `dept`, that's safe to use in email handles and URL paths. You can also create custom dimensions and attributes of your own, which [Attribute Conditions](https://docs.provisionr.io/concepts/control/policies.md#attribute-conditions) describes.

### Enabled Dimensions

We detect every dimension that exists, but we only create attribute records for a dimension once you enable attributes for it. This allows you to opt in to how much of your data is stored in Provisionr.

Each dimension has an `attributes_enabled` field that is `false` by default. When it's `true`, we collect the unique values of that key across your users during each sync, and we create an Attribute record for each value, linked to its dimension by `directory_dimension_id`.

You only need to enable attributes for the organizational dimensions that you want to use in policies. You wouldn't use `employeeNumber` or `firstName` in a policy, for example, but you'll likely want `department` and `title`. Before you enable a dimension, you can preview all of its unique attributes to check that it contains useful data for policy conditions. Once you enable attributes for a dimension, they can't be disabled again, so it's a good idea to check the preview first.

When your Workspace Integration is synced for the first time, we check each dimension against a list of sensible defaults for the vendor and enable attributes for the ones on the list. For Okta, these dimensions have attributes enabled by default:

* `organization`
* `title`
* `division`
* `department`
* `costCenter`
* `countryCode`
* `timezone`

These are the dimensions with attributes enabled for Ian's integration, with the profile key of each one highlighted.

```json Directory Dimensions with Attributes Enabled highlight={5,15,25,35} theme={null}
[
    {
        "id": "drdim_01kgst083631whd34e10e03tn9",
        "integration_id": "okitg_01kgst0661n7j9natpk42xp12v",
        "profile_key": "costCenter",
        "name": "Cost Center",
        "handle": "cost-center",
        "created_at": "2026-02-06T15:44:18.000000Z",
        "updated_at": "2026-02-06T15:44:18.000000Z",
        "state": "active"
    },
    {
        "id": "drdim_01kgst0845m862d8sza6wpvxck",
        "integration_id": "okitg_01kgst0661n7j9natpk42xp12v",
        "profile_key": "division",
        "name": "Division",
        "handle": "division",
        "created_at": "2026-02-06T15:44:18.000000Z",
        "updated_at": "2026-02-06T15:44:18.000000Z",
        "state": "active"
    },
    {
        "id": "drdim_01kgst085d5jr6pq2mvzxa9hae",
        "integration_id": "okitg_01kgst0661n7j9natpk42xp12v",
        "profile_key": "department",
        "name": "Department",
        "handle": "dept",
        "created_at": "2026-02-06T15:44:18.000000Z",
        "updated_at": "2026-02-06T15:44:18.000000Z",
        "state": "active"
    },
    {
        "id": "drdim_01kgst086tz8vypg3jqcf43cc7",
        "integration_id": "okitg_01kgst0661n7j9natpk42xp12v",
        "profile_key": "title",
        "name": "Title",
        "handle": "title",
        "created_at": "2026-02-06T15:44:18.000000Z",
        "updated_at": "2026-02-06T15:44:18.000000Z",
        "state": "active"
    }
]
```

## Directory Attributes

When we import identities, we look at their profile data and find all of the unique values of each key whose dimension has `attributes_enabled` set to `true`. These values are the dimension's **Attributes**.

During each scheduled sync, we look for new values and import each one as a new attribute. When a value is no longer found, its attribute is deprecated and expires 30 days later, whichever dimension it belongs to. Once the attribute reaches its expiration date, the next sync soft deletes it and deactivates its policy, and everyone on that policy goes with it.

That 30-day countdown belongs to the attribute, and it's separate from how long each person keeps the attribute after they stop qualifying for it. While the attribute still exists, a person's grace period comes from the attribute's ruleset, which inherits the dimension's grace period unless the ruleset or one of its rules sets its own. A grace period never runs past the attribute's expiration date, so one that would end later is brought forward to that date. [Inheriting and Overriding Grace Periods](https://docs.provisionr.io/concepts/control/qualification.md#inheriting-and-overriding-grace-periods) explains how each level inherits from the one above it.

These are the attributes of the Department dimension, with `IT` highlighted.

```json Attributes of the Department Dimension highlight={12} theme={null}
{
    "dratr_01kgstampeargmtahvnvgbfawf": "Accounting",
    "dratr_01kgstane2a0vhx97dkg7zqfwc": "Brand Marketing",
    "dratr_01kgstap7n0076snpzx9p8hxhm": "Business Development",
    "dratr_01kgstaq0jbxg92wmddfdempwa": "Content Marketing",
    "dratr_01kgstaqzcvpnk35zamdnmsz66": "Customer Success",
    "dratr_01kgstarv8pgtan1xwcfe21p45": "Enterprise Sales",
    "dratr_01kgstasj31nwgcfz79mbwba24": "Executive Office",
    "dratr_01kgstatbgeytd055yrxn38smf": "Field Marketing",
    "dratr_01kgstatt9cezypx73banzjjnz": "Financial Planning",
    "dratr_01kgstav94b4qe1hha2tqgp2dd": "HR Operations",
    "dratr_01kgstavxctryyfg46k2dnepqc": "IT",
    "dratr_01kgstawn9q2kzfkbpynpz3095": "Legal",
    "dratr_01kgstaxfm76efmnsmeka78t9a": "Marketing Leadership",
    "dratr_01kgstay89sekwf2ycb71ygvp8": "Mid-Market Sales",
    "dratr_01kgstayv1mk64731v07c74e1s": "Office of the CFO",
    "dratr_01kgstazd7n2ycp9k4aea60saa": "Office of the CTO",
    "dratr_01kgstb00xgjnwx6zmv00a8216": "Product Design",
    "dratr_01kgstb0eg006b14fpbe704sw2": "Product Development",
    "dratr_01kgstb10e1zsmz91g5wqaka8n": "Product Infrastructure",
    "dratr_01kgstb1pt83szjs0878y0axe1": "Product Management",
    "dratr_01kgstb26y934czy56bsgwhhf5": "Product Security",
    "dratr_01kgstb2zvm590342z0b95s4e5": "Product Support",
    "dratr_01kgstb3fv2bnjfr3r5xzzreg8": "Professional Services",
    "dratr_01kgstb3xje6jbmj8gm274zdmd": "Recruiting",
    "dratr_01kgstb4gwr6zt45chkxqmj2g4": "Sales Analytics",
    "dratr_01kgstb56zahdns55qw199hzh5": "Sales Leadership",
    "dratr_01kgstb64mhwva791semn3hmes": "Small Business Sales",
    "dratr_01kgstb6y5qwgdh95m1j37zhq7": "Tax",
}
```

Each attribute is its own record, linked to the dimension that it belongs to. This allows us to manage the lifecycle of each attribute, and its relationships to rules and policies, by relational database ID rather than by string matching.

```json IT Department Attribute Data highlight={2,8} 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",
    "deprecated_at": null,
    "expires_at": null,
    "deleted_at": null,
    "state": "active",
}
```

These are the fields that you'll use most often when you work with attributes in your policies.

| Field | What it records |
| - | - |
| `directory_dimension_id` | The dimension that the attribute belongs to. |
| `policy_ruleset_id` | The attribute's own Policy Ruleset. Each attribute is a policy, and its rules decide who holds the attribute. See [Policies & Rules](https://docs.provisionr.io/concepts/control/policies.md). |
| `type` | `integration` for an attribute imported from your integration, `ruleset` for a custom attribute that an administrator created, or `catch` for a catch-all attribute for the people who don't meet the criteria, such as `Unknown`. |
| `profile_value` | The profile value that the attribute was imported from. |
| `directory_attribute_id_successor` | The attribute that replaced this one, for example after a rename. It's empty until a successor is set. |
| `deprecated_at` | When the attribute was deprecated and its countdown began. It's empty while the attribute is current, and it's cleared if the attribute is reactivated. |
| `expires_at` | The attribute's expiration date, which is set when the attribute is deprecated. It's empty while the attribute is current. |

## Attribute Lifecycle Changes

If you use string-matching rules today, you're already working with dimensions and attributes, even if you haven't called them that. A rule like `department equals engineering` treats `department` as the dimension and `engineering` as the attribute.

Now imagine that the department is renamed to `Software Development`. With string matching, you'd need to find and update every rule that references `Engineering`, and any rule that you miss stops matching without telling anyone. This comes up often for administrators, and it's one of the main reasons that attributes are records of their own in the Provisionr policy engine.

Provisionr maintains a single source of truth for every dimension and its unique attribute values, detected automatically from the users in your IdP directory. Instead of matching the raw string `department equals engineering`, we store a Dimension record for `Department` and an Attribute record for `Engineering`. Each record has its own ID, timestamps, and state, and rules reference these records by ID rather than by name, which means that the relationships between rules, dimensions, and attributes are managed through stable references rather than string matching.

When a value changes in your IdP, for example because a department was renamed in your HRIS, the next sync treats the new value as a new attribute, because nothing in the imported data says that the two values are related. The old attribute is deprecated and starts counting down to its expiration date, and the new attribute is imported alongside it. A new profile key works the same way, and it becomes a new dimension.

If you know about the rename ahead of time, you can keep the existing record instead. Each attribute has a `profile_value`, which is what the sync matches against your imported data, and a `name`, which is what you see in Provisionr. When you [update the attribute](https://docs.provisionr.io/cli/workspace/v1/directory-attribute/update.md) so that its `profile_value` is the new value, the sync keeps matching the same attribute, with the same ID and every rule that references it. The `name` stays as it was unless you change it, so a department can be renamed at the source while it keeps its old name in Provisionr. A dimension works in the same way, through its `profile_key` and its `name`.

Make this update before the next sync if you can, because once a sync has imported the new value, it's already a separate attribute. In that case, you can link the two with `directory_attribute_id_successor`, so that the predecessor records the attribute that replaced it. This link is there for history and audit discovery, so that you can follow an attribute forward to the one that replaced it, in the same way that a rule version records its successor in [Rule Rollback](https://docs.provisionr.io/integrations/okta/rollback).

All of this gives you better visibility into your policies as your organization changes. You don't need to track down string-matching rules spread across many policies, and the audit trail shows what changed, when, and why.

## Dimension Deprecation

A dimension can stop appearing in your integration's API, and when it does, we don't want that to cause an unexpected breaking change in your policies.

So rather than removing the dimension right away, we deprecate it. We use the dimension's grace period, which is its own `expires_after_days` or the workspace default of 30 days when it doesn't set one, to set the expiration date of the dimension and of each of its attributes.

This gives you a log alert, which is recorded as a `directory.dimension.deprecate.success` event, along with a notice period in the UI and time for your administrators to update the rules that are affected.

If you need more time, you can change the dimension's expiration date by [deprecating the dimension](https://docs.provisionr.io/cli/workspace/v1/directory-dimension/deprecate.md) again with a new `expires_at`. If the key was renamed in your integration rather than removed, you can [update the dimension](https://docs.provisionr.io/cli/workspace/v1/directory-dimension/update.md) so that its `profile_key` is the new key. You can also convert the dimension from an imported dimension to a custom dimension, which preserves the existing attributes and attached users. Keep in mind that a custom dimension no longer has a source of information, so its data stays frozen in time unless you change it yourself.

After the expiration date has passed, the dimension and each of its attributes are soft deleted, and each attribute's own policy is deactivated. You can [reactivate](https://docs.provisionr.io/cli/workspace/v1/directory-dimension/activate.md) these records, which soft restores them, if you need to.

The rules and conditions that reference these records aren't deactivated along with them, so update any rules that are affected before the expiration date.

## Logging Dimensions and Attributes

Each change to a dimension or an attribute is written to the workspace [event log](https://docs.provisionr.io/concepts/workspace/logs.md) at the `info` level. These are the events that you'll see most often.

| Event | Recorded when | What to look for |
| - | - | - |
| `directory.dimension.import.success` | A sync finds a new profile key and imports it as a dimension | The new dimension is the record, and its integration is the parent |
| `directory.attribute.import.success` | A sync finds a new value of an enabled dimension and imports it as an attribute | `attribute_key` and `attribute_value_new`, which hold the profile key and the new value |
| `directory.attribute.deprecate.success` | A value is no longer found, or an administrator deprecates the attribute | `metadata.expires_at`, and `metadata.expiring_users_shortened`, which is the number of people whose grace period now ends with the attribute |
| `directory.attribute.update.successor` | A new attribute is created to replace an earlier one | `metadata.predecessor` and `metadata.successor` |
| `directory.attribute.expired.deleted` | An attribute reaches its expiration date and is soft deleted | `metadata.users_count`, `metadata.type`, and `metadata.directory_attribute_id_successor` |
| `directory.dimension.deprecate.success` | A profile key is no longer found, or an administrator deprecates the dimension | `metadata.expires_at` |
| `directory.dimension.expired.delete.success` | A dimension reaches its expiration date and is soft deleted | `metadata.attributes_count` |

Creating, activating, and deactivating a dimension or an attribute are recorded as well, with events such as `directory.attribute.create.success`, `directory.attribute.activate.success`, and `directory.attribute.deactivate.success`.

## API Reference

Since dimensions and attributes are records of their own, you can query users by a specific attribute value without parsing each user's profile JSON. These API endpoints are available:

* [`/api/v1/directory/dimensions`](https://docs.provisionr.io/api/workspace/v1/directory-dimensions/list-of-dimensions)
* [`/api/v1/directory/dimensions/{ulid}`](https://docs.provisionr.io/api/workspace/v1/directory-dimensions/describe-a-dimension)
* [`/api/v1/directory/attributes/{ulid}`](https://docs.provisionr.io/api/workspace/v1/directory-attributes/describe-an-attribute)
* [`/api/v1/directory/users`](https://docs.provisionr.io/api/workspace/v1/directory-users/list-of-users)

Related records are reached through filters on the list endpoints, which you can combine with any other filter in the same request.

| To list | Request |
| - | - |
| The attributes of a dimension | `GET /api/v1/directory/attributes?filter[directory_dimension_id]=drdim_...` |
| The people who hold an attribute | `GET /api/v1/policy/users?filter[policy_ruleset_id]=poset_...`, using the attribute's `policy_ruleset_id` |
| Everything that a person holds | `GET /api/v1/policy/users?filter[directory_user_id]=drusr_...` |

The [`directory-dimension`](https://docs.provisionr.io/cli/workspace/v1/directory-dimension/list) and [`directory-attribute`](https://docs.provisionr.io/cli/workspace/v1/directory-attribute/list) commands in the CLI work with the same records.

***

Dimensions and attributes give us the vocabulary for describing the people in your directory. The next page looks at how policies use that vocabulary to decide who gets access to what.

[Continue reading: Policies & Rules →](https://docs.provisionr.io/concepts/control/policies.md)


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