Create a Dimension

curl --request POST \
  --url https://wksusa1b2c3d.provisionr.app/api/v1/directory/dimensions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Sales Region",
  "handle": "sales-region",
  "expires_after_days": 30,
  "activate": false
}
'

$headers=@{}
$headers.Add("Authorization", "Bearer <token>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://wksusa1b2c3d.provisionr.app/api/v1/directory/dimensions' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "name": "Sales Region",
  "handle": "sales-region",
  "expires_after_days": 30,
  "activate": false
}'

import requests

url = "https://wksusa1b2c3d.provisionr.app/api/v1/directory/dimensions"

payload = {
    "name": "Sales Region",
    "handle": "sales-region",
    "expires_after_days": 30,
    "activate": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Sales Region',
    handle: 'sales-region',
    expires_after_days: 30,
    activate: false
  })
};

fetch('https://wksusa1b2c3d.provisionr.app/api/v1/directory/dimensions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "drdim_01hq8xyzabc123def456ghi789",
  "state": "staged",
  "integration_id": "gitg_01hq8xyzabc123def456ghi789",
  "integration_type": "App\\Models\\GoogleIntegration",
  "profile_key": "department",
  "name": "Department",
  "handle": "dept",
  "attributes_enabled": true,
  "conditions_enabled": true,
  "expires_after_days": 30,
  "metadata": {},
  "timestamp": {
    "created_at": "2025-01-28T13:37:00Z",
    "updated_at": "2025-05-04T03:27:00Z",
    "activated_at": "2025-03-14T15:07:00Z",
    "expires_at": null,
    "deleted_at": null
  },
  "count": [
    "<string>"
  ],
  "included": {
    "directory_attributes": [
      {
        "id": "dratr_01hq8xyzabc123def456ghi789",
        "state": "active",
        "type": "integration",
        "parent": "Department",
        "name": "Engineering",
        "handle": "eng",
        "blueprint_signature": "{blueprint_id_last4}-{dimension_id}-{attribute_id}-{ref_id}",
        "profile_value": "Engineering"
      }
    ],
    "integration": {
      "id": "gitg_01hq8xyzabc123def456ghi789",
      "vendor": "google",
      "is_primary": true
    }
  },
  "links": {
    "self": "<string>",
    "directory_attributes": "<string>",
    "integration": "<string>"
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

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

POST

directory

dimensions

Create a Dimension

curl --request POST \
  --url https://wksusa1b2c3d.provisionr.app/api/v1/directory/dimensions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Sales Region",
  "handle": "sales-region",
  "expires_after_days": 30,
  "activate": false
}
'

$headers=@{}
$headers.Add("Authorization", "Bearer <token>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://wksusa1b2c3d.provisionr.app/api/v1/directory/dimensions' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "name": "Sales Region",
  "handle": "sales-region",
  "expires_after_days": 30,
  "activate": false
}'

import requests

url = "https://wksusa1b2c3d.provisionr.app/api/v1/directory/dimensions"

payload = {
    "name": "Sales Region",
    "handle": "sales-region",
    "expires_after_days": 30,
    "activate": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Sales Region',
    handle: 'sales-region',
    expires_after_days: 30,
    activate: false
  })
};

fetch('https://wksusa1b2c3d.provisionr.app/api/v1/directory/dimensions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "drdim_01hq8xyzabc123def456ghi789",
  "state": "staged",
  "integration_id": "gitg_01hq8xyzabc123def456ghi789",
  "integration_type": "App\\Models\\GoogleIntegration",
  "profile_key": "department",
  "name": "Department",
  "handle": "dept",
  "attributes_enabled": true,
  "conditions_enabled": true,
  "expires_after_days": 30,
  "metadata": {},
  "timestamp": {
    "created_at": "2025-01-28T13:37:00Z",
    "updated_at": "2025-05-04T03:27:00Z",
    "activated_at": "2025-03-14T15:07:00Z",
    "expires_at": null,
    "deleted_at": null
  },
  "count": [
    "<string>"
  ],
  "included": {
    "directory_attributes": [
      {
        "id": "dratr_01hq8xyzabc123def456ghi789",
        "state": "active",
        "type": "integration",
        "parent": "Department",
        "name": "Engineering",
        "handle": "eng",
        "blueprint_signature": "{blueprint_id_last4}-{dimension_id}-{attribute_id}-{ref_id}",
        "profile_value": "Engineering"
      }
    ],
    "integration": {
      "id": "gitg_01hq8xyzabc123def456ghi789",
      "vendor": "google",
      "is_primary": true
    }
  },
  "links": {
    "self": "<string>",
    "directory_attributes": "<string>",
    "integration": "<string>"
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

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

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

CreateDirectoryDimensionRequestData

name

string

required

Title Case human readable name

Maximum string length: 63

Example:

"Sales Region"

handle

string | null

alpha-dash string that is similar to the name or uses shorthand abbreviations. If not set, the name will be converted to alpha-dash format. This is used for generating group names in email addresses or URL paths

Maximum string length: 55

Example:

"sales-region"

expires_after_days

integer | null

Number of days that users are still a manifest user after being deprecated for a graceful transition. This dimension-level value is inherited by child attributes and rulesets as the default. If not set, this value is inherited from the global workspace value

Required range: 0 <= x <= 1095

Example:

30

activate

boolean

default:false

By default (false) the status is set to STAGED. Set to true to set to ACTIVE. This allows the resource to be created and then activated in a separate step. This prevents the resource from being activated before it is fully configured

Response

DirectoryDimensionDetailedResponseData

string

required

Example:

"drdim_01hq8xyzabc123def456ghi789"

state

enum<string>

required

The state of the directory dimension


`staged` The record is staged and is only visible to administrators or in the API. Use the `activate` method during your change window.
`active` The record is active.
`expiring` The `expires_at` value is set in the future for the record. You can run the `activate` action to remove the scheduled expiration.
`expired` The `expires_at` value is in the past and the record was deactivated.
`deactivated` The record was deactivated manually by an administrator.

Available options:

staged,

active,

expiring,

expired,

deactivated

integration_id

string | null

required

The ID of the integration this dimension was sourced from (polymorphic).

Use this together with integration_type when creating an identity-type Policy Condition

Example:

"gitg_01hq8xyzabc123def456ghi789"

integration_type

string | null

required

The type of the integration this dimension was sourced from (polymorphic).

This is the value expected by integration_type when creating an identity-type Policy Condition

Example:

"App\\Models\\GoogleIntegration"

profile_key

string | null

required

The name of the key from the Workspace Integration that is in the Identity metadata array to get values from

Example:

"department"

name

string

required

The display name of the dimension. Any dimensions that are imported from the Integration are formatted with Headline/Title case

Example:

"Department"

handle

string

required

The alpha dash, lowercase abbreviated name of the dimension that is safe to use in email handles and URL paths

Example:

"dept"

attributes_enabled

boolean

required

If enabled, a Directory Attribute record is automatically created for each Dimension Attribute value from the unique Identity metadata profile_key values

conditions_enabled

boolean

required

If disabled, Attributes in this Dimension will not appear in the list of available options when creating a Rule Condition.

This is used when you want to have metadata about users but do not want future maintenance burden with rulesets using this data

expires_after_days

integer | null

required

Users will be automatically deprecated if they no longer qualify for at least one rule in the ruleset.

The expires_after_days value determines how many days after they no longer qualify that they still have access for a graceful transition period when users change job roles.

The value is inherited from the Workspace > Dimension > Attribute/Resource > Rule and can be overridden at any level to provide shorter revoke time controls when needed.

If the value is 0, this skips the grace period and revokes access immediately after expires_at.

By default, users have perpetual access (as Policy Users) as long as their attributes continue to match the conditions for the rule. If the rule is designed for just-in-time or short term access, you can set the expires_at date for all conditional users to be deprecated at that time.

You can use expires_at and expires_after_days=0 together to revoke access immediately.

Best Practice: You should the "low risk" sensible default (ex. 30 days) at the Dimension level and set more strict values at the Attribute/Resource levels where an exception needs to be granted.

A null value means no override is set at this level, so the grace period is inherited from the parent level

Example:

30

metadata

object

required

The dimension's custom key/value metadata added by someone or automation in your organization

Show child attributes

timestamp

TimestampStateData · object

required

The timestamps for the directory dimension record

Show child attributes

count

string[]

required

Counts of related resources.

directory_attributes: int|null audit_logs_parent: int|null, audit_logs_record: int|null, audit_logs_related: int|null, }

Minimum array length: 1

included

object

required

Included related resources

Show child attributes

links

object

required

API hyperlinks related to the directory dimension record

Show child attributes

Getting Started

Endpoints

Create a Dimension

Authorizations

Body

Response