OneLake Data Access Security - Create Or Update Data Access Roles

Service:: Core

API Version:: v1

Creates or updates data access roles in OneLake.

Note

This API is part of a Preview release and is provided for evaluation and development purposes only. It may change based on feedback and is not recommended for production use.

Required Delegated Scopes

OneLake.ReadWrite.All

Microsoft Entra supported identities

This API supports the Microsoft identities listed in this section.

Identity	Support
User	Yes
Service principal and Managed identities	Yes

Interface

PUT https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/dataAccessRoles

With optional parameters:

PUT https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/dataAccessRoles?dryRun={dryRun}

URI Parameters

Name	In	Required	Type	Description
itemId	path	True	string (uuid)	The ID of the Fabric item to put the roles.
workspaceId	path	True	string (uuid)	The workspace ID.
dryRun	query		boolean	Used to trigger a dry run of the API call. True - The API call will trigger a dry run and no roles will be changed. False - Will not trigger a dry run and roles will be updated.

Request Header

Name	Required	Type	Description
If-Match		string	An ETag value. The ETag must be specified in quotes. If provided, the call will succeed only if the resource's ETag matches the provided ETag.
If-None-Match		string	An ETag value. The ETag must be specified in quotes. If provided, the call will succeed only if the resource's ETag doesn't match the provided ETag.

Request Body

Name	Type	Description
value	DataAccessRole[]	A list of roles that are used to manage data access security and ensure that only authorized users can view certain data. A role represents a set of permissions and permission scopes that define what actions its members are allowed to perform for the data in scope. Members are users or groups who have been granted the role, and they can read the data based on the permissions assigned to the role. For example, a member can be a Microsoft Entra ID group and permission scope can be a Read Action applied on the given Path to File, Folder(s) or Table(s) in OneLake.

Responses

Name	Type	Description
200 OK		Request completed successfully. Headers Etag: string
Other Status Codes	ErrorResponse	Common error codes: ItemNotFound - Indicates that the server can't find the requested item. PreconditionFailed -Indicates that the current resource ETag doesn't match the value specified in the If-Match header.

Name

Type

Description

200 OK

Request completed successfully.

Headers

Etag: string

Other Status Codes

ErrorResponse

Common error codes:

ItemNotFound - Indicates that the server can't find the requested item.
PreconditionFailed -Indicates that the current resource ETag doesn't match the value specified in the If-Match header.

Examples

Create or update data access roles example

Create or update data access roles with constraints example

Create or update data access roles with tables path example

Create or update data access roles example

Sample request

HTTP

PUT https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff222/items/25bac802-080d-4f73-8a42-1b406eb1fceb/dataAccessRoles

{
  "value": [
    {
      "name": "default_role_1",
      "decisionRules": [
        {
          "effect": "Permit",
          "permission": [
            {
              "attributeName": "Path",
              "attributeValueIncludedIn": [
                "*"
              ]
            },
            {
              "attributeName": "Action",
              "attributeValueIncludedIn": [
                "Read"
              ]
            }
          ]
        }
      ],
      "members": {
        "fabricItemMembers": [
          {
            "itemAccess": [
              "ReadAll"
            ],
            "sourcePath": "cfafbeb1-8037-4d0c-896e-a46fb27ff222/25bac802-080d-4f73-8a42-1b406eb1fceb"
          }
        ]
      }
    }
  ]
}

Sample response

Status code:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with constraints example

Sample request

HTTP

PUT https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff222/items/25bac802-080d-4f73-8a42-1b406eb1fceb/dataAccessRoles

{
  "value": [
    {
      "name": "default_role_1",
      "decisionRules": [
        {
          "effect": "Permit",
          "permission": [
            {
              "attributeName": "Path",
              "attributeValueIncludedIn": [
                "*"
              ]
            },
            {
              "attributeName": "Action",
              "attributeValueIncludedIn": [
                "Read"
              ]
            }
          ],
          "constraints": {
            "columns": [
              {
                "tablePath": "/Tables/industrytable",
                "columnNames": [
                  "Industry"
                ],
                "columnEffect": "Permit",
                "columnAction": [
                  "Read"
                ]
              }
            ],
            "rows": [
              {
                "tablePath": "/Tables/industrytable",
                "value": "select * from Industrytable where Industry=\"Green\""
              }
            ]
          }
        }
      ],
      "members": {
        "fabricItemMembers": [
          {
            "itemAccess": [
              "ReadAll"
            ],
            "sourcePath": "cfafbeb1-8037-4d0c-896e-a46fb27ff222/25bac802-080d-4f73-8a42-1b406eb1fceb"
          }
        ]
      }
    }
  ]
}

Sample response

Status code:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with tables path example

Sample request

HTTP

PUT https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff222/items/25bac802-080d-4f73-8a42-1b406eb1fceb/dataAccessRoles

{
  "value": [
    {
      "name": "default_role_1",
      "decisionRules": [
        {
          "effect": "Permit",
          "permission": [
            {
              "attributeName": "Path",
              "attributeValueIncludedIn": [
                "/Tables/sales",
                "/Tables/users"
              ]
            },
            {
              "attributeName": "Action",
              "attributeValueIncludedIn": [
                "Read"
              ]
            }
          ]
        }
      ],
      "members": {
        "fabricItemMembers": [
          {
            "itemAccess": [
              "ReadAll"
            ],
            "sourcePath": "cfafbeb1-8037-4d0c-896e-a46fb27ff222/25bac802-080d-4f73-8a42-1b406eb1fceb"
          }
        ]
      }
    }
  ]
}

Sample response

Status code:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d5

Definitions

Name	Description
AttributeName	Specifies the name of the attribute that is being evaluated for access permissions. AttributeName can be `Path` or `Action`. Additional attributeName types may be added over time.
ColumnAction	The array of actions applied to the columnNames. This determines which actions a user will be able to perform on columns. The allowed values are: Read. Additional columnAction types may be added over time.
ColumnConstraint	ColumnConstraint indicates a constraint that determines the permissions and visibility a user has on columns within a table.
ColumnEffect	The effect given to the columnNames. The only allowed value is Permit. Additional columnEffect types may be added over time.
Constraints	Any constraints such as row or column level security that are applied to tables as part of this role. If not included, no constraints apply to any tables in the role.
CreateOrUpdateDataAccessRolesRequest	Contains definition of Roles that are used to manage data access security and ensure that only authorized users can view, edit, or delete certain data. Calling this API updates role definitions and creates, updates, or deletes roles to match the provided payload.
DataAccessRole	A Data access role represents a set of permissions and permission scopes that define what actions its members are allowed to perform for the data in scope. Data access roles are used to manage data access security and ensure that only authorized users can view, edit, or delete certain data. Members are users or groups who have been granted the role, and they can read the data based on the permissions assigned to the role. For example, a member can be an Microsoft Entra ID group and permission scope can be a Read Action applied on the given Path to File, Folder(s) or Table(s) in OneLake.
DecisionRule	Specifies a rule for matching the requested action. Contains effect (Permit) and Permission which determine whether a user or entity is authorized to perform a specific action (e.g., read) on a resource. Permission is a set of scopes, defined by attributes, that must match the requested action for the rule to apply.
Effect	The effect that a role has on access to the data resource. Currently, the only supported effect type is `Permit`, which grants access to the resource. Additional effect types may be added over time.
ErrorRelatedResource	The error related resource details object.
ErrorResponse	The error response.
ErrorResponseDetails	The error response details.
FabricItemMember	Fabric item member.
ItemAccess	A list specifying the access permissions for Fabric user to have to be automatically included in the role members. Additional itemAccess types may be added over time.
Members	The members object which contains the members of the role as arrays of different member types.
MicrosoftEntraMember	Microsoft Entra ID member assigned to the role.
ObjectType	The type of Microsoft Entra ID object. Additional objectType types may be added over time.
PermissionScope	Defines a set of attributes (properties) that determine the scope and level of access to a resource. When `attributeName` property is set to `Path`, the `attributeValueIncludedIn` property must specify the location of the resource being accessed, such as "Tables/Table1". When the `attributeName` property is set to `Action`, the `attributeValueIncludedIn` property must specify the type of access being granted, such as `Read`.
RowConstraint	RowConstraint indicates a constraint that determines the rows in a table that users can see. Roles defined with RowConstraints use T-SQL to define a predicate that filters data in a table. Rows that do not meet the predicate’s conditions are filtered out, leaving a subset of the original rows. RowConstraints can also be used to specify dynamic and multi-table flavors of RLS using T-SQL.

AttributeName

Enumeration

Specifies the name of the attribute that is being evaluated for access permissions. AttributeName can be Path or Action. Additional attributeName types may be added over time.

Value	Description
Path	Attribute name Path
Action	Attribute name Action

ColumnAction

Enumeration

The array of actions applied to the columnNames. This determines which actions a user will be able to perform on columns. The allowed values are: Read. Additional columnAction types may be added over time.

Value	Description
Read	The ColumnAction value Read

ColumnConstraint

Object

ColumnConstraint indicates a constraint that determines the permissions and visibility a user has on columns within a table.

Name	Type	Description
columnAction	ColumnAction[]	The array of actions applied to the columnNames. This determines which actions a user will be able to perform on columns. The allowed values are: Read. Additional columnAction types may be added over time.
columnEffect	ColumnEffect	The effect given to the columnNames. The only allowed value is Permit. Additional columnEffect types may be added over time.
columnNames	string[]	An array of case sensitive column names. Each value is a column name from the table specified in `tablePath`. Use these columns with `columnEffect` and `columnAction`. Columns that aren't listed get the default value null. Use `*` to indicate all columns in the table.
tablePath	string	A relative file path specifying which table the column constraint applies to. This should be in the form of `/Tables/{optionalSchema}/{tableName}`. Only one value can be given here and the tableName must be a table included in the PermissionScope.

ColumnEffect

Enumeration

The effect given to the columnNames. The only allowed value is Permit. Additional columnEffect types may be added over time.

Value	Description
Permit	The ColumnEffect type Permit

Constraints

Object

Any constraints such as row or column level security that are applied to tables as part of this role. If not included, no constraints apply to any tables in the role.

Name	Type	Description
columns	ColumnConstraint[]	The array of column constraints applied to one or more tables in the data access role.
rows	RowConstraint[]	The array of row constraints applied to one or more tables in the data access role.

CreateOrUpdateDataAccessRolesRequest

Object

Contains definition of Roles that are used to manage data access security and ensure that only authorized users can view, edit, or delete certain data. Calling this API updates role definitions and creates, updates, or deletes roles to match the provided payload.

Name	Type	Description
value	DataAccessRole[]	A list of roles that are used to manage data access security and ensure that only authorized users can view certain data. A role represents a set of permissions and permission scopes that define what actions its members are allowed to perform for the data in scope. Members are users or groups who have been granted the role, and they can read the data based on the permissions assigned to the role. For example, a member can be a Microsoft Entra ID group and permission scope can be a Read Action applied on the given Path to File, Folder(s) or Table(s) in OneLake.

DataAccessRole

Object

A Data access role represents a set of permissions and permission scopes that define what actions its members are allowed to perform for the data in scope. Data access roles are used to manage data access security and ensure that only authorized users can view, edit, or delete certain data. Members are users or groups who have been granted the role, and they can read the data based on the permissions assigned to the role. For example, a member can be an Microsoft Entra ID group and permission scope can be a Read Action applied on the given Path to File, Folder(s) or Table(s) in OneLake.

Name	Type	Description
decisionRules	DecisionRule[]	The array of permissions that make up the Data access role.
id	string (uuid)	The unique id for the Data access role.
members	Members	The members object which contains the members of the role as arrays of different member types.
name	string	The name of the Data access role.

DecisionRule

Object

Specifies a rule for matching the requested action. Contains effect (Permit) and Permission which determine whether a user or entity is authorized to perform a specific action (e.g., read) on a resource. Permission is a set of scopes, defined by attributes, that must match the requested action for the rule to apply.

Name	Type	Description
constraints	Constraints	Any constraints such as row or column level security that are applied to tables as part of this role. If not included, no constraints apply to any tables in the role.
effect	Effect	The effect that a role has on access to the data resource. Currently, the only supported effect type is `Permit`, which grants access to the resource. Additional effect types may be added over time.
permission	PermissionScope[]	The `permission` property is an array that specifies the scope and level of access for a requested action. The array must contain exactly two PermissionScope objects: `Path` and `Action`. The `scope` is defined using the `PermissionScope` object, with `attributeValueIncludedIn` specifying either the location of the resource being accessed or the type of action being granted. The `access` refers to the level of access being granted, such as `Read`.

Effect

Enumeration

The effect that a role has on access to the data resource. Currently, the only supported effect type is Permit, which grants access to the resource. Additional effect types may be added over time.

Value	Description
Permit	the effect type Permit

ErrorRelatedResource

Object

The error related resource details object.

Name	Type	Description
resourceId	string	The resource ID that's involved in the error.
resourceType	string	The type of the resource that's involved in the error.

ErrorResponse

Object

The error response.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message	string	A human readable representation of the error.
moreDetails	ErrorResponseDetails[]	List of additional error details.
relatedResource	ErrorRelatedResource	The error related resource details.
requestId	string	ID of the request associated with the error.

ErrorResponseDetails

Object

The error response details.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message	string	A human readable representation of the error.
relatedResource	ErrorRelatedResource	The error related resource details.

FabricItemMember

Object

Fabric item member.

Name	Type	Description
itemAccess	ItemAccess[]	A list specifying the access permissions for Fabric user to have to be automatically included in the role members. Additional itemAccess types may be added over time.
sourcePath	string pattern: ^[{]?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}[}]?/[{]?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}[}]?$	The path to Fabric item having the specified item access.

ItemAccess

Enumeration

A list specifying the access permissions for Fabric user to have to be automatically included in the role members. Additional itemAccess types may be added over time.

Value	Description
Read	Item Access Read.
Write	Item Access Write.
Reshare	Item Access Reshare.
Explore	Item Access Explore.
Execute	Item Access Execute.
ReadAll	Item Access ReadAll.

Members

Object

The members object which contains the members of the role as arrays of different member types.

Name	Type	Description
fabricItemMembers	FabricItemMember[]	A list of members who have a certain permission set in Microsoft Fabric. All members with that permission set are added as members of this Data Access Role.
microsoftEntraMembers	MicrosoftEntraMember[]	The list of Microsoft Entra ID members.

MicrosoftEntraMember

Object

Microsoft Entra ID member assigned to the role.

Name	Type	Description
objectId	string (uuid)	The object id.
objectType	ObjectType	The type of Microsoft Entra ID object. Additional objectType types may be added over time.
tenantId	string (uuid)	The tenant id.

ObjectType

Enumeration

The type of Microsoft Entra ID object. Additional objectType types may be added over time.

Value	Description
Group	Attribute name Group
User	Attribute name User
ServicePrincipal	Attribute name ServicePrincipal
ManagedIdentity	Attribute name ManagedIdentity

PermissionScope

Object

Defines a set of attributes (properties) that determine the scope and level of access to a resource. When attributeName property is set to Path, the attributeValueIncludedIn property must specify the location of the resource being accessed, such as "Tables/Table1". When the attributeName property is set to Action, the attributeValueIncludedIn property must specify the type of access being granted, such as Read.

Name	Type	Description
attributeName	AttributeName	Specifies the name of the attribute that is being evaluated for access permissions. AttributeName can be `Path` or `Action`. Additional attributeName types may be added over time.
attributeValueIncludedIn	string[]	Specifies a list of values for the `attributeName` to define the scope and the level of access to a resource. When `attributeName` is `Path`, `attributeValueIncludedIn` must specify the location of the resource being accessed, such as "Tables/Table1". When `attributeName` is `Action`, the `attributeValueIncludedIn` must specify the type of access being granted, such as `Read`.

RowConstraint

Object

RowConstraint indicates a constraint that determines the rows in a table that users can see. Roles defined with RowConstraints use T-SQL to define a predicate that filters data in a table. Rows that do not meet the predicate’s conditions are filtered out, leaving a subset of the original rows. RowConstraints can also be used to specify dynamic and multi-table flavors of RLS using T-SQL.

Name	Type	Description
tablePath	string	A relative file path specifying which table the row constraint applies to. This should be in the form of `/Tables/{optionalSchema}/{tableName}`. Only one value can be given here and the tableName must be a table included in the PermissionScope.
value	string	A T-SQL expression that is used to evaluate which rows the role members can see. Only a subset of T-SQL can be used as a predicate.

Share via

OneLake Data Access Security - Create Or Update Data Access Roles

Required Delegated Scopes

Microsoft Entra supported identities

Interface

URI Parameters

Request Header

Request Body

Responses

Examples

Create or update data access roles example

Sample request

Sample response

Create or update data access roles with constraints example

Sample request

Sample response

Create or update data access roles with tables path example

Sample request

Sample response

Definitions

AttributeName

ColumnAction

ColumnConstraint

ColumnEffect

Constraints

CreateOrUpdateDataAccessRolesRequest

DataAccessRole

DecisionRule

Effect

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

FabricItemMember

ItemAccess

Members

MicrosoftEntraMember

ObjectType

PermissionScope

RowConstraint