Create a Dimension

POST /directory/dimensions

Create a Dimension

cURL

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

201

{
  "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.

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

201

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