OneLake Data Access Security - Create Or Update Data Access Roles

Reference

Service:: Core

API Version:: v1

Note

This API is in preview.

Creates or updates data access roles in OneLake.

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	Yes
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 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 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.
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`.

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.

Name	Type	Description
Action	string	Attribute name Action
Path	string	Attribute name Path

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.

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

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

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

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.

Name	Type	Description
Permit	string	the effect type Permit

ErrorRelatedResource

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

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

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

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	The path to Fabric item having the specified item access.

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.

Name	Type	Description
Execute	string	Item Access Execute.
Explore	string	Item Access Explore.
Read	string	Item Access Read.
ReadAll	string	Item Access ReadAll.
Reshare	string	Item Access Reshare.
Write	string	Item Access Write.

Members

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

Microsoft Entra ID member assigned to the role.

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

ObjectType

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

Name	Type	Description
Group	string	Attribute name Group
ManagedIdentity	string	Attribute name ManagedIdentity
ServicePrincipal	string	Attribute name ServicePrincipal
User	string	Attribute name User

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.

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`.

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 tables path example

Sample request

Sample response

Definitions

AttributeName

CreateOrUpdateDataAccessRolesRequest

DataAccessRole

DecisionRule

Effect

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

FabricItemMember

ItemAccess

Members

MicrosoftEntraMember

ObjectType

PermissionScope

Additional resources