Update a Dimension

PATCH /directory/dimensions/{dimension}

Update a Dimension

cURL

curl --request PATCH \
  --url https://wks-a1b2c3d4.provisionr.io/api/v1/directory/dimensions/{dimension} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "handle": "<string>",
  "profile_key": "<string>",
  "attributes_enabled": true,
  "expires_after_days": 547
}
'

202

{
  "id": "<string>",
  "state": "staged",
  "profile_key": "<string>",
  "name": "<string>",
  "handle": "<string>",
  "attributes_enabled": true,
  "conditions_enabled": true,
  "expires_after_days": 123,
  "metadata": {},
  "timestamp": {
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "activated_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z"
  },
  "count": [
    "<string>"
  ],
  "included": {
    "directory_attributes": [
      {
        "id": "<string>",
        "state": "staged",
        "type": "integration",
        "parent": "<string>",
        "name": "<string>",
        "handle": "<string>",
        "blueprint_signature": "<string>",
        "profile_value": "<string>"
      }
    ],
    "workspace_integration": {
      "id": "<string>",
      "is_primary": true,
      "vendor": "demo",
      "handle": "<string>",
      "domain": "<string>"
    }
  },
  "links": {
    "self": "<string>",
    "directory_attributes": "<string>",
    "workspace_integration": "<string>"
  }
}

Authorizations

Authorization · string · header · required

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

Path Parameters

dimension · string · required

Directory Dimension ID

Body

application/json

UpdateDirectoryDimensionRequestData

name · string

The name of the directory dimension

Maximum string length: 63

Example:

"Department"

handle · string

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

Maximum string length: 55

Example:

"dept"

profile_key · string

If the profile key for this dimension is renamed in the integration, you can update to the new key

Maximum string length: 255

attributes_enabled · boolean

For dimensions that were imported by identity metadata keys, attributes are only created if they will be used for rulesets. A few sensible defaults are enabled. You can update the dimension to create attributes for all of the unique values in the respective identity metadata key. Once enabled, this cannot be disabled

expires_after_days · integer

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. This only applies to attributes that have not overridden the value with their own setting and newly created attributes

Required range: 0 <= x <= 1095

Example:

30

Response

202

application/json

DirectoryDimensionDetailedResponseData

id · 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

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 · 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

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 workspace_logs_parent: int|null, workspace_logs_record: int|null, workspace_logs_related: int|null, }

included · object · required

Included related resources

Show child attributes

links · object · required

API hyperlinks related to the directory dimension record

Show child attributes