Skip to main content

Create a Role

POST 

/roles

This API creates a role. In addition, a ROLE_SUBADMIN may not create a role including an access profile if that access profile is associated with a source the ROLE_SUBADMIN is not associated with themselves.

The maximum supported length for the description field is 2000 characters. Longer descriptions will be preserved for existing roles. However, any new roles as well as any updates to existing descriptions will be limited to 2000 characters.

Request

Body

required

    id string

    The id of the Role. This field must be left null when creating an Role, otherwise a 400 Bad Request error will result.

    name stringrequired

    Possible values: <= 128 characters

    The human-readable display name of the Role

    description stringnullable

    A human-readable description of the Role

    owner

    object

    required

    The owner of this object.

    type string

    Possible values: [IDENTITY]

    Owner type. This field must be either left null or set to 'IDENTITY' on input, otherwise a 400 Bad Request error will result.

    id string

    Identity id

    name string

    Human-readable display name of the owner. It may be left null or omitted in a POST or PATCH. If set, it must match the current value of the owner's display name, otherwise a 400 Bad Request error will result.

    accessProfiles

    object[]

    nullable

  • Array [

  • id string

    ID of the Access Profile

    type string

    Possible values: [ACCESS_PROFILE]

    Type of requested object. This field must be either left null or set to 'ACCESS_PROFILE' when creating an Access Profile, otherwise a 400 Bad Request error will result.

    name string

    Human-readable display name of the Access Profile. This field is ignored on input.

  • ]

  • entitlements

    object[]

  • Array [

  • type string

    Possible values: [ENTITLEMENT]

    Entitlement's DTO type.

    id string

    Entitlement's ID.

    name stringnullable

    Entitlement's display name.

  • ]

  • membership

    object

    nullable

    When present, specifies that the Role is to be granted to Identities which either satisfy specific criteria or which are members of a given list of Identities.

    type RoleMembershipSelectorType (string)

    Possible values: [STANDARD, IDENTITY_LIST]

    This enum characterizes the type of a Role's membership selector. Only the following two are fully supported:

    STANDARD: Indicates that Role membership is defined in terms of a criteria expression

    IDENTITY_LIST: Indicates that Role membership is conferred on the specific identities listed

    criteria

    object

    nullable

    Defines STANDARD type Role membership

    operation RoleCriteriaOperation (string)

    Possible values: [EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH, AND, OR]

    An operation

    key

    object

    nullable

    Refers to a specific Identity attribute, Account attibute, or Entitlement used in Role membership criteria

    type RoleCriteriaKeyType (string)required

    Possible values: [IDENTITY, ACCOUNT, ENTITLEMENT]

    Indicates whether the associated criteria represents an expression on identity attributes, account attributes, or entitlements, respectively.

    property stringrequired

    The name of the attribute or entitlement to which the associated criteria applies.

    sourceId stringnullable

    ID of the Source from which an account attribute or entitlement is drawn. Required if type is ACCOUNT or ENTITLEMENT

    stringValue stringnullable

    String value to test the Identity attribute, Account attribute, or Entitlement specified in the key w/r/t the specified operation. If this criteria is a leaf node, that is, if the operation is one of EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, or ENDS_WITH, this field is required. Otherwise, specifying it is an error.

    children

    object[]

    nullable

    Array of child criteria. Required if the operation is AND or OR, otherwise it must be left null. A maximum of three levels of criteria are supported, including leaf nodes. Additionally, AND nodes can only be children or OR nodes and vice-versa.

  • Array [

  • operation RoleCriteriaOperation (string)

    Possible values: [EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH, AND, OR]

    An operation

    key

    object

    nullable

    Refers to a specific Identity attribute, Account attibute, or Entitlement used in Role membership criteria

    type RoleCriteriaKeyType (string)required

    Possible values: [IDENTITY, ACCOUNT, ENTITLEMENT]

    Indicates whether the associated criteria represents an expression on identity attributes, account attributes, or entitlements, respectively.

    property stringrequired

    The name of the attribute or entitlement to which the associated criteria applies.

    sourceId stringnullable

    ID of the Source from which an account attribute or entitlement is drawn. Required if type is ACCOUNT or ENTITLEMENT

    stringValue stringnullable

    String value to test the Identity attribute, Account attribute, or Entitlement specified in the key w/r/t the specified operation. If this criteria is a leaf node, that is, if the operation is one of EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, or ENDS_WITH, this field is required. Otherwise, specifying it is an error.

    children

    object[]

    nullable

    Array of child criteria. Required if the operation is AND or OR, otherwise it must be left null. A maximum of three levels of criteria are supported, including leaf nodes. Additionally, AND nodes can only be children or OR nodes and vice-versa.

  • Array [

  • operation RoleCriteriaOperation (string)

    Possible values: [EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH, AND, OR]

    An operation

    key

    object

    nullable

    Refers to a specific Identity attribute, Account attibute, or Entitlement used in Role membership criteria

    type RoleCriteriaKeyType (string)required

    Possible values: [IDENTITY, ACCOUNT, ENTITLEMENT]

    Indicates whether the associated criteria represents an expression on identity attributes, account attributes, or entitlements, respectively.

    property stringrequired

    The name of the attribute or entitlement to which the associated criteria applies.

    sourceId stringnullable

    ID of the Source from which an account attribute or entitlement is drawn. Required if type is ACCOUNT or ENTITLEMENT

    stringValue string

    String value to test the Identity attribute, Account attribute, or Entitlement specified in the key w/r/t the specified operation. If this criteria is a leaf node, that is, if the operation is one of EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, or ENDS_WITH, this field is required. Otherwise, specifying it is an error.

  • ]

  • ]

  • identities

    object[]

    nullable

    Defines role membership as being exclusive to the specified Identities, when type is IDENTITY_LIST.

  • Array [

  • type DtoType (string)nullable

    Possible values: [ACCOUNT_CORRELATION_CONFIG, ACCESS_PROFILE, ACCESS_REQUEST_APPROVAL, ACCOUNT, APPLICATION, CAMPAIGN, CAMPAIGN_FILTER, CERTIFICATION, CLUSTER, CONNECTOR_SCHEMA, ENTITLEMENT, GOVERNANCE_GROUP, IDENTITY, IDENTITY_PROFILE, IDENTITY_REQUEST, LIFECYCLE_STATE, PASSWORD_POLICY, ROLE, RULE, SOD_POLICY, SOURCE, TAG, TAG_CATEGORY, TASK_RESULT, REPORT_RESULT, SOD_VIOLATION, ACCOUNT_ACTIVITY, WORKGROUP]

    An enumeration of the types of DTOs supported within the IdentityNow infrastructure.

    id string

    Identity id

    name stringnullable

    Human-readable display name of the Identity.

    aliasName stringnullable

    User name of the Identity

  • ]

  • legacyMembershipInfo

    object

    nullable

    This field is not directly modifiable and is generally expected to be null. In very rare instances, some Roles may have been created using membership selection criteria that are no longer fully supported. While these Roles will still work, they should be migrated to STANDARD or IDENTITY_LIST selection criteria. This field exists for informational purposes as an aid to such migration.

    property name* anynullable

    This field is not directly modifiable and is generally expected to be null. In very rare instances, some Roles may have been created using membership selection criteria that are no longer fully supported. While these Roles will still work, they should be migrated to STANDARD or IDENTITY_LIST selection criteria. This field exists for informational purposes as an aid to such migration.

    enabled boolean

    Whether the Role is enabled or not.

    requestable boolean

    Whether the Role can be the target of access requests.

    accessRequestConfig

    object

    nullable

    Access request configuration for this object

    commentsRequired booleannullable

    Whether the requester of the containing object must provide comments justifying the request

    denialCommentsRequired booleannullable

    Whether an approver must provide comments when denying the request

    approvalSchemes

    object[]

    List describing the steps in approving the request

  • Array [

  • approverType string

    Possible values: [OWNER, MANAGER, GOVERNANCE_GROUP]

    Describes the individual or group that is responsible for an approval step. Values are as follows.

    OWNER: Owner of the associated Role

    MANAGER: Manager of the Identity making the request

    GOVERNANCE_GROUP: A Governance Group, the ID of which is specified by the approverId field

    approverId stringnullable

    Id of the specific approver, used only when approverType is GOVERNANCE_GROUP

  • ]

  • revocationRequestConfig

    object

    nullable

    Revocation request configuration for this object.

    commentsRequired booleannullable

    Whether the requester of the containing object must provide comments justifying the request

    denialCommentsRequired booleannullable

    Whether an approver must provide comments when denying the request

    approvalSchemes

    object[]

    List describing the steps in approving the revocation request

  • Array [

  • approverType string

    Possible values: [OWNER, MANAGER, GOVERNANCE_GROUP]

    Describes the individual or group that is responsible for an approval step. Values are as follows.

    OWNER: Owner of the associated Role

    MANAGER: Manager of the Identity making the request

    GOVERNANCE_GROUP: A Governance Group, the ID of which is specified by the approverId field

    approverId stringnullable

    Id of the specific approver, used only when approverType is GOVERNANCE_GROUP

  • ]

  • segments string[]nullable

    List of IDs of segments, if any, to which this Role is assigned.

    dimensional booleannullable

    Whether the Role is dimensional.

    dimensionRefs

    object[]

    nullable

    List of references to dimensions to which this Role is assigned. This field is only relevant if the Role is dimensional.

  • Array [

  • type string

    Possible values: [DIMENSION]

    The type of the object to which this reference applies

    id string

    ID of the object to which this reference applies

    name string

    Human-readable display name of the object to which this reference applies

  • ]

  • accessModelMetadata

    object[]

  • Array [

  • attributes

    object[]

    nullable

  • Array [

  • key string

    Technical name of the Attribute. This is unique and cannot be changed after creation.

    name string

    The display name of the key.

    multiselect boolean

    Indicates whether the attribute can have multiple values.

    status string

    The status of the Attribute.

    type string

    The type of the Attribute. This can be either "custom" or "governance".

    objectTypes string[]nullable

    An array of object types this attributes values can be applied to. Possible values are "all" or "entitlement". Value "all" means this attribute can be used with all object types that are supported.

    description string

    The description of the Attribute.

    values

    object[]

    nullable

  • Array [

  • value string

    Technical name of the Attribute value. This is unique and cannot be changed after creation.

    name string

    The display name of the Attribute value.

    status string

    The status of the Attribute value.

  • ]

  • ]

  • ]

Responses

Role created

Schema

    id string

    The id of the Role. This field must be left null when creating an Role, otherwise a 400 Bad Request error will result.

    name stringrequired

    Possible values: <= 128 characters

    The human-readable display name of the Role

    created date-time

    Date the Role was created

    modified date-time

    Date the Role was last modified.

    description stringnullable

    A human-readable description of the Role

    owner

    object

    required

    The owner of this object.

    type string

    Possible values: [IDENTITY]

    Owner type. This field must be either left null or set to 'IDENTITY' on input, otherwise a 400 Bad Request error will result.

    id string

    Identity id

    name string

    Human-readable display name of the owner. It may be left null or omitted in a POST or PATCH. If set, it must match the current value of the owner's display name, otherwise a 400 Bad Request error will result.

    accessProfiles

    object[]

    nullable

  • Array [

  • id string

    ID of the Access Profile

    type string

    Possible values: [ACCESS_PROFILE]

    Type of requested object. This field must be either left null or set to 'ACCESS_PROFILE' when creating an Access Profile, otherwise a 400 Bad Request error will result.

    name string

    Human-readable display name of the Access Profile. This field is ignored on input.

  • ]

  • entitlements

    object[]

  • Array [

  • type string

    Possible values: [ENTITLEMENT]

    Entitlement's DTO type.

    id string

    Entitlement's ID.

    name stringnullable

    Entitlement's display name.

  • ]

  • membership

    object

    nullable

    When present, specifies that the Role is to be granted to Identities which either satisfy specific criteria or which are members of a given list of Identities.

    type RoleMembershipSelectorType (string)

    Possible values: [STANDARD, IDENTITY_LIST]

    This enum characterizes the type of a Role's membership selector. Only the following two are fully supported:

    STANDARD: Indicates that Role membership is defined in terms of a criteria expression

    IDENTITY_LIST: Indicates that Role membership is conferred on the specific identities listed

    criteria

    object

    nullable

    Defines STANDARD type Role membership

    operation RoleCriteriaOperation (string)

    Possible values: [EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH, AND, OR]

    An operation

    key

    object

    nullable

    Refers to a specific Identity attribute, Account attibute, or Entitlement used in Role membership criteria

    type RoleCriteriaKeyType (string)required

    Possible values: [IDENTITY, ACCOUNT, ENTITLEMENT]

    Indicates whether the associated criteria represents an expression on identity attributes, account attributes, or entitlements, respectively.

    property stringrequired

    The name of the attribute or entitlement to which the associated criteria applies.

    sourceId stringnullable

    ID of the Source from which an account attribute or entitlement is drawn. Required if type is ACCOUNT or ENTITLEMENT

    stringValue stringnullable

    String value to test the Identity attribute, Account attribute, or Entitlement specified in the key w/r/t the specified operation. If this criteria is a leaf node, that is, if the operation is one of EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, or ENDS_WITH, this field is required. Otherwise, specifying it is an error.

    children

    object[]

    nullable

    Array of child criteria. Required if the operation is AND or OR, otherwise it must be left null. A maximum of three levels of criteria are supported, including leaf nodes. Additionally, AND nodes can only be children or OR nodes and vice-versa.

  • Array [

  • operation RoleCriteriaOperation (string)

    Possible values: [EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH, AND, OR]

    An operation

    key

    object

    nullable

    Refers to a specific Identity attribute, Account attibute, or Entitlement used in Role membership criteria

    type RoleCriteriaKeyType (string)required

    Possible values: [IDENTITY, ACCOUNT, ENTITLEMENT]

    Indicates whether the associated criteria represents an expression on identity attributes, account attributes, or entitlements, respectively.

    property stringrequired

    The name of the attribute or entitlement to which the associated criteria applies.

    sourceId stringnullable

    ID of the Source from which an account attribute or entitlement is drawn. Required if type is ACCOUNT or ENTITLEMENT

    stringValue stringnullable

    String value to test the Identity attribute, Account attribute, or Entitlement specified in the key w/r/t the specified operation. If this criteria is a leaf node, that is, if the operation is one of EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, or ENDS_WITH, this field is required. Otherwise, specifying it is an error.

    children

    object[]

    nullable

    Array of child criteria. Required if the operation is AND or OR, otherwise it must be left null. A maximum of three levels of criteria are supported, including leaf nodes. Additionally, AND nodes can only be children or OR nodes and vice-versa.

  • Array [

  • operation RoleCriteriaOperation (string)

    Possible values: [EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH, AND, OR]

    An operation

    key

    object

    nullable

    Refers to a specific Identity attribute, Account attibute, or Entitlement used in Role membership criteria

    type RoleCriteriaKeyType (string)required

    Possible values: [IDENTITY, ACCOUNT, ENTITLEMENT]

    Indicates whether the associated criteria represents an expression on identity attributes, account attributes, or entitlements, respectively.

    property stringrequired

    The name of the attribute or entitlement to which the associated criteria applies.

    sourceId stringnullable

    ID of the Source from which an account attribute or entitlement is drawn. Required if type is ACCOUNT or ENTITLEMENT

    stringValue string

    String value to test the Identity attribute, Account attribute, or Entitlement specified in the key w/r/t the specified operation. If this criteria is a leaf node, that is, if the operation is one of EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, or ENDS_WITH, this field is required. Otherwise, specifying it is an error.

  • ]

  • ]

  • identities

    object[]

    nullable

    Defines role membership as being exclusive to the specified Identities, when type is IDENTITY_LIST.

  • Array [

  • type DtoType (string)nullable

    Possible values: [ACCOUNT_CORRELATION_CONFIG, ACCESS_PROFILE, ACCESS_REQUEST_APPROVAL, ACCOUNT, APPLICATION, CAMPAIGN, CAMPAIGN_FILTER, CERTIFICATION, CLUSTER, CONNECTOR_SCHEMA, ENTITLEMENT, GOVERNANCE_GROUP, IDENTITY, IDENTITY_PROFILE, IDENTITY_REQUEST, LIFECYCLE_STATE, PASSWORD_POLICY, ROLE, RULE, SOD_POLICY, SOURCE, TAG, TAG_CATEGORY, TASK_RESULT, REPORT_RESULT, SOD_VIOLATION, ACCOUNT_ACTIVITY, WORKGROUP]

    An enumeration of the types of DTOs supported within the IdentityNow infrastructure.

    id string

    Identity id

    name stringnullable

    Human-readable display name of the Identity.

    aliasName stringnullable

    User name of the Identity

  • ]

  • legacyMembershipInfo

    object

    nullable

    This field is not directly modifiable and is generally expected to be null. In very rare instances, some Roles may have been created using membership selection criteria that are no longer fully supported. While these Roles will still work, they should be migrated to STANDARD or IDENTITY_LIST selection criteria. This field exists for informational purposes as an aid to such migration.

    property name* anynullable

    This field is not directly modifiable and is generally expected to be null. In very rare instances, some Roles may have been created using membership selection criteria that are no longer fully supported. While these Roles will still work, they should be migrated to STANDARD or IDENTITY_LIST selection criteria. This field exists for informational purposes as an aid to such migration.

    enabled boolean

    Whether the Role is enabled or not.

    requestable boolean

    Whether the Role can be the target of access requests.

    accessRequestConfig

    object

    nullable

    Access request configuration for this object

    commentsRequired booleannullable

    Whether the requester of the containing object must provide comments justifying the request

    denialCommentsRequired booleannullable

    Whether an approver must provide comments when denying the request

    approvalSchemes

    object[]

    List describing the steps in approving the request

  • Array [

  • approverType string

    Possible values: [OWNER, MANAGER, GOVERNANCE_GROUP]

    Describes the individual or group that is responsible for an approval step. Values are as follows.

    OWNER: Owner of the associated Role

    MANAGER: Manager of the Identity making the request

    GOVERNANCE_GROUP: A Governance Group, the ID of which is specified by the approverId field

    approverId stringnullable

    Id of the specific approver, used only when approverType is GOVERNANCE_GROUP

  • ]

  • revocationRequestConfig

    object

    nullable

    Revocation request configuration for this object.

    commentsRequired booleannullable

    Whether the requester of the containing object must provide comments justifying the request

    denialCommentsRequired booleannullable

    Whether an approver must provide comments when denying the request

    approvalSchemes

    object[]

    List describing the steps in approving the revocation request

  • Array [

  • approverType string

    Possible values: [OWNER, MANAGER, GOVERNANCE_GROUP]

    Describes the individual or group that is responsible for an approval step. Values are as follows.

    OWNER: Owner of the associated Role

    MANAGER: Manager of the Identity making the request

    GOVERNANCE_GROUP: A Governance Group, the ID of which is specified by the approverId field

    approverId stringnullable

    Id of the specific approver, used only when approverType is GOVERNANCE_GROUP

  • ]

  • segments string[]nullable

    List of IDs of segments, if any, to which this Role is assigned.

    dimensional booleannullable

    Whether the Role is dimensional.

    dimensionRefs

    object[]

    nullable

    List of references to dimensions to which this Role is assigned. This field is only relevant if the Role is dimensional.

  • Array [

  • type string

    Possible values: [DIMENSION]

    The type of the object to which this reference applies

    id string

    ID of the object to which this reference applies

    name string

    Human-readable display name of the object to which this reference applies

  • ]

  • accessModelMetadata

    object[]

  • Array [

  • attributes

    object[]

    nullable

  • Array [

  • key string

    Technical name of the Attribute. This is unique and cannot be changed after creation.

    name string

    The display name of the key.

    multiselect boolean

    Indicates whether the attribute can have multiple values.

    status string

    The status of the Attribute.

    type string

    The type of the Attribute. This can be either "custom" or "governance".

    objectTypes string[]nullable

    An array of object types this attributes values can be applied to. Possible values are "all" or "entitlement". Value "all" means this attribute can be used with all object types that are supported.

    description string

    The description of the Attribute.

    values

    object[]

    nullable

  • Array [

  • value string

    Technical name of the Attribute value. This is unique and cannot be changed after creation.

    name string

    The display name of the Attribute value.

    status string

    The status of the Attribute value.

  • ]

  • ]

  • ]

Loading...