OneLake Data Access Security - Get Data Access Role

Service:: Core

API Version:: v1

Returns data access role details for the given role name.

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.

When calling this API, callers must specify true as the value for the query parameter preview.

Permissions

The caller must have member or higher role on the workspace.

Required Delegated Scopes

OneLake.Read.All or 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

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

URI Parameters

Name	In	Required	Type	Description
itemId	path	True	string (uuid)	The ID of the Fabric item to get the role from.
roleName	path	True	string	The name of the role to retrieve.
workspaceId	path	True	string (uuid)	The workspace ID.

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.

Responses

Name Type Description

200 OK

Name	Type	Description
200 OK	DataAccessRoleBase	Request completed successfully. Headers ETag: string
429 Too Many Requests	ErrorResponse	The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests. Headers Retry-After: integer
Other Status Codes	ErrorResponse	Common error codes: ItemNotFound - Indicates that the server cannot find the requested item. RoleNotFound - Indicates that the specified role was not found. PreconditionFailed - Indicates that the current resource ETag doesn't match the value specified in the If-Match header.

DataAccessRoleBase

Request completed successfully.

Headers

ETag: string

429 Too Many Requests

ErrorResponse

The service rate limit was exceeded. The server returns a Retry-After header indicating, in seconds, how long the client must wait before sending additional requests.

Headers

Retry-After: integer

Other Status Codes

ErrorResponse

Common error codes:

ItemNotFound - Indicates that the server cannot find the requested item.
RoleNotFound - Indicates that the specified role was not found.
PreconditionFailed - Indicates that the current resource ETag doesn't match the value specified in the If-Match header.

Examples

Get data access role example

Sample request

HTTP

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

Sample response

Status code:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

{
  "name": "DefaultReader",
  "decisionRules": [
    {
      "effect": "Permit",
      "permission": [
        {
          "attributeName": "Path",
          "attributeValueIncludedIn": [
            "Tables/schema1",
            "Tables/schema2/TableB"
          ]
        },
        {
          "attributeName": "Action",
          "attributeValueIncludedIn": [
            "Read",
            "ReadWrite"
          ]
        }
      ],
      "constraints": {
        "columns": [
          {
            "tablePath": "Tables/schema1/TableB",
            "columnNames": [
              "*"
            ],
            "columnEffect": "Permit",
            "columnAction": [
              "Read"
            ]
          }
        ],
        "rows": [
          {
            "tablePath": "Tables/schema1/TableC",
            "value": "select * from [schema1].[TableC] where name = 'Aaron' AND country = 'USA'"
          }
        ]
      }
    }
  ],
  "members": {
    "fabricItemMembers": [
      {
        "sourcePath": "cfafbeb1-8037-4d0c-896e-a46fb27ff222/25bac802-080d-4f73-8a42-1b406eb1fceb",
        "itemAccess": [
          "ReadAll"
        ]
      }
    ],
    "microsoftEntraMembers": [
      {
        "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
        "objectId": "EAF3B3B8-524A-4EC6-A96F-3340748DF869"
      }
    ]
  }
}

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.
DataAccessRoleBase	Base data access role object used for single-role operations (does not include id). Represents a set of permissions and permission scopes that define allowed actions for scoped data.
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.

DataAccessRoleBase

Object

Base data access role object used for single-role operations (does not include id). Represents a set of permissions and permission scopes that define allowed actions for scoped data.

Name	Type	Description
decisionRules	DecisionRule[]	The array of permissions that make up 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 (uuid)	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 - Get Data Access Role

Permissions

Required Delegated Scopes

Microsoft Entra supported identities

Interface

URI Parameters

Request Header

Responses

Examples

Get data access role example

Sample request

Sample response

Definitions

AttributeName

ColumnAction

ColumnConstraint

ColumnEffect

Constraints

DataAccessRoleBase

DecisionRule

Effect

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

FabricItemMember

ItemAccess

Members

MicrosoftEntraMember

ObjectType

PermissionScope

RowConstraint