Microsoft Fabric One Lake Data Access Security API

openapi: 3.2.0
info:
  title: Microsoft Fabric Platform REST One Lake Data Access…
  version: v1
  x-source: 'https://github.com/microsoft/fabric-rest-api-specs (bundled from openapi/_original/fabric-rest-api-specs: platform/swagger.json)'
servers:
- url: https://api.fabric.microsoft.com/v1
security: []
tags:
- name: OneLakeDataAccessSecurity
paths:
  /workspaces/{workspaceId}/items/{itemId}/dataAccessRoles:
    get:
      summary: Returns a list of OneLake roles
      description: '## 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'
      tags:
      - OneLakeDataAccessSecurity
      operationId: OneLakeDataAccessSecurity_ListDataAccessRoles
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: itemId
        description: The ID of the Fabric item to put the roles.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: continuationToken
        description: A token for retrieving the next page of results.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Request completed successfully.
          headers:
            Etag:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAccessRoles'
        '429':
          description: 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.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: 'Common error codes:


            * ItemNotFound - Indicates that the server cannot find the requested item.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      summary: Creates or updates data access roles in OneLake
      description: '## 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'
      tags:
      - OneLakeDataAccessSecurity
      operationId: OneLakeDataAccessSecurity_CreateOrUpdateDataAccessRoles
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: itemId
        description: The ID of the Fabric item to put the roles.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: dryRun
        description: 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.
        required: false
        schema:
          type: boolean
      - in: header
        name: If-Match
        description: 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.
        required: false
        schema:
          type: string
      - in: header
        name: If-None-Match
        description: 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.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Request completed successfully.
          headers:
            Etag:
              schema:
                type: string
        '429':
          description: 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.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: '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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateDataAccessRolesRequest'
        description: Contains definition of roles 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.
        required: true
    post:
      summary: Creates or updates (upserts) a single data access role
      description: '**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.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'
      tags:
      - OneLakeDataAccessSecurity
      operationId: OneLakeDataAccessSecurity_CreateOrUpdateSingleDataAccessRole
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: itemId
        description: The ID of the Fabric item to create or update the role on.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: dataAccessRoleConflictPolicy
        description: Determines the behavior when there are conflicting data access role assignments. Overwrite means new assignments replace existing ones. Abort means the operation fails if there are conflicts. Additional dataAccessRoleConflictPolicy types may be added over time.
        x-ms-enum:
          name: DataAccessRoleConflictPolicy
          modelAsString: true
          values:
          - value: Overwrite
            description: Create a new role or overwrite existing role with the provided definition.
          - value: Abort
            description: Abort the operation when there is a conflict with an existing role.
        required: false
        schema:
          type: string
          enum:
          - Overwrite
          - Abort
      - in: header
        name: If-Match
        description: 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.
        required: false
        schema:
          type: string
      - in: header
        name: If-None-Match
        description: 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.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Request completed successfully.
          headers:
            ETag:
              description: Unique identifier for the resource, used for concurrency control
              schema:
                type: string
            Location:
              description: URL of the created role resource.
              schema:
                type: string
        '201':
          description: Role created successfully.
          headers:
            ETag:
              description: Unique identifier for the resource, used for concurrency control
              schema:
                type: string
            Location:
              description: URL of the created role resource.
              schema:
                type: string
        '429':
          description: 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.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: 'Common error codes:


            * ItemNotFound - Indicates that the server cannot find the requested item.


            * PreconditionFailed - Indicates that the current resource ETag doesn''t match the value specified in the If-Match header.


            * Conflict - There are conflicting role assignments and the conflict policy is set to Abort.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataAccessRoleBase'
        description: A single data access role definition (without id).
        required: true
  /workspaces/{workspaceId}/items/{itemId}/dataAccessRoles/{roleName}:
    get:
      summary: Returns data access role details for the given role name
      description: '**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'
      tags:
      - OneLakeDataAccessSecurity
      operationId: OneLakeDataAccessSecurity_GetDataAccessRole
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: itemId
        description: The ID of the Fabric item to get the role from.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: roleName
        description: The name of the role to retrieve.
        required: true
        schema:
          type: string
      - in: header
        name: If-Match
        description: 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.
        required: false
        schema:
          type: string
      - in: header
        name: If-None-Match
        description: 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.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Request completed successfully.
          headers:
            ETag:
              description: Unique identifier for the resource, used for concurrency control
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAccessRoleBase'
        '429':
          description: 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.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: '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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Deletes a single data access role
      description: '**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.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'
      tags:
      - OneLakeDataAccessSecurity
      operationId: OneLakeDataAccessSecurity_DeleteDataAccessRole
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: itemId
        description: The ID of the Fabric item to delete the role from.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: roleName
        description: The name of the role to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Request completed successfully.
        '429':
          description: 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.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: 'Common error codes:


            * ItemNotFound - Indicates that the server cannot find the requested item.


            * RoleNotFound - Indicates that the specified role was not found.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      description: The error response.
      required:
      - message
      - errorCode
      allOf:
      - $ref: '#/components/schemas/ErrorResponseDetails'
      properties:
        requestId:
          type: string
          format: uuid
          description: ID of the request associated with the error.
          readOnly: true
        moreDetails:
          description: List of additional error details.
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseDetails'
          readOnly: true
        isRetriable:
          type: boolean
          description: When true, the request can be retried. Use the `Retry-After` response header to determine the delay, if available.
          readOnly: true
    DataAccessRoles:
      required:
      - value
      type: object
      properties:
        value:
          description: 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.
          type: array
          items:
            $ref: '#/components/schemas/DataAccessRoleListItem'
      allOf:
      - $ref: '#/components/schemas/PaginatedResponse'
    DataAccessRole:
      description: Full data access role object including server-assigned id.
      allOf:
      - $ref: '#/components/schemas/DataAccessRoleBase'
      - type: object
        description: Extends base data access role with server-assigned read-only id property.
        properties:
          id:
            description: The unique id for the Data access role.
            type: string
            format: uuid
            readOnly: true
    DecisionRule:
      description: 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.
      type: object
      required:
      - permission
      properties:
        effect:
          description: 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.
          type: string
          enum:
          - Permit
          x-ms-enum:
            name: Effect
            modelAsString: true
            values:
            - value: Permit
              description: the effect type Permit
        permission:
          description: '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`.'
          type: array
          items:
            $ref: '#/components/schemas/PermissionScope'
          minItems: 2
          maxItems: 2
        constraints:
          description: '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. '
          type: object
          properties:
            columns:
              description: The array of column constraints applied to one or more tables in the data access role.
              type: array
              items:
                $ref: '#/components/schemas/ColumnConstraint'
            rows:
              description: The array of row constraints applied to one or more tables in the data access role.
              type: array
              items:
                $ref: '#/components/schemas/RowConstraint'
    DataAccessRoleListItem:
      description: Data access role object returned by list operations. Includes the entity tag (ETag) used for concurrency control.
      allOf:
      - $ref: '#/components/schemas/DataAccessRole'
      - type: object
        properties:
          eTag:
            description: Entity tag for the role, used for concurrency control.
            type: string
    ColumnConstraint:
      description: ColumnConstraint indicates a constraint that determines the permissions and visibility a user has on columns within a table.
      type: object
      required:
      - tablePath
      - columnNames
      - columnAction
      - columnEffect
      properties:
        tablePath:
          description: 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.
          type: string
        columnNames:
          description: 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.
          type: array
          items:
            type: string
        columnEffect:
          description: The effect given to the columnNames. The only allowed value is *Permit*. Additional columnEffect types may be added over time.
          type: string
          enum:
          - Permit
          x-ms-enum:
            name: ColumnEffect
            modelAsString: true
            values:
            - value: Permit
              description: The ColumnEffect type Permit
        columnAction:
          description: '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.'
          type: array
          items:
            type: string
            enum:
            - Read
            x-ms-enum:
              name: ColumnAction
              modelAsString: true
              values:
              - value: Read
                description: The ColumnAction value Read
    MicrosoftEntraMember:
      description: Microsoft Entra ID member assigned to the role.
      type: object
      required:
      - tenantId
      - objectId
      properties:
        tenantId:
          description: The tenant id.
          type: string
          format: uuid
        objectId:
          description: The object id.
          type: string
          format: uuid
    PermissionScope:
      description: 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`.
      type: object
      required:
      - attributeName
      - attributeValueIncludedIn
      properties:
        attributeName:
          description: 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.
          type: string
          enum:
          - Path
          - Action
          x-ms-enum:
            name: AttributeName
            modelAsString: true
            values:
            - value: Path
              description: Attribute name Path
            - value: Action
              description: Attribute name Action
        attributeValueIncludedIn:
          description: "Specifies a list of values for the `attributeName` to define the scope and the level of access to a resource. \nWhen `attributeName` is `Path`, `attributeValueIncludedIn` must specify the location of the resource being accessed, such as \"Tables/Table1\".\nWhen `attributeName` is `Action`, the `attributeValueIncludedIn` must specify the type of access being granted, such as `Read`."
          type: array
          items:
            type: string
    ErrorResponseDetails:
      description: The error response details.
      type: object
      required:
      - message
      - errorCode
      properties:
        errorCode:
          type: string
          description: A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
          readOnly: true
        message:
          type: string
          description: A human readable representation of the error.
          readOnly: true
        relatedResource:
          $ref: '#/components/schemas/ErrorRelatedResource'
        parameters:
          description: Structured parameters providing additional machine-readable context about the error.
          type: array
          items:
            $ref: '#/components/schemas/ErrorParameter'
          readOnly: true
    ErrorRelatedResource:
      description: The error related resource details object.
      type: object
      required:
      - resourceId
      - resourceType
      properties:
        resourceId:
          type: string
          description: The resource ID that's involved in the error.
          readOnly: true
        resourceType:
          type: string
          description: The type of the resource that's involved in the error.
          readOnly: true
    DataAccessRoleBase:
      description: 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.
      type: object
      required:
      - name
      - decisionRules
      properties:
        name:
          description: The name of the Data access role.
          type: string
        kind:
          description: The kind of the Data access role. Currently, the only supported kind is `Policy`. Additional kind types may be added over time.
          type: string
          enum:
          - Policy
          x-ms-enum:
            name: DataAccessRoleKind
            modelAsString: true
            values:
            - value: Policy
              description: Policy-based data access role.
        decisionRules:
          description: The array of permissions that make up the Data access role.
          type: array
          items:
            $ref: '#/components/schemas/DecisionRule'
        members:
          $ref: '#/components/schemas/Members'
    FabricItemMember:
      description: Fabric item member.
      type: object
      required:
      - itemAccess
      - sourcePath
      properties:
        itemAccess:
          description: 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.
          type: array
          items:
            type: string
            enum:
            - Read
            - Write
            - Reshare
            - Explore
            - Execute
            - ReadAll
            x-ms-enum:
              name: ItemAccess
              modelAsString: true
              values:
              - value: Read
                description: Item Access Read.
              - value: Write
                description: Item Access Write.
              - value: Reshare
                description: Item Access Reshare.
              - value: Explore
                description: Item Access Explore.
              - value: Execute
                description: Item Access Execute.
              - value: ReadAll
                description: Item Access ReadAll.
        sourcePath:
          description: The path to Fabric item having the specified item access.
          type: 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}[}]?$
    CreateOrUpdateDataAccessRolesRequest:
      description: 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.
      type: object
      properties:
        value:
          description: 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.
          type: array
          items:
            $ref: '#/components/schemas/DataAccessRole'
    RowConstraint:
      description: 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.
      type: object
      required:
      - tablePath
      - value
      properties:
        tablePath:
          description: 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.
          type: string
        value:
          description: 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.
          type: string
    PaginatedResponse:
      properties:
        continuationToken:
          type: string
          description: The token for the next result set batch. If there are no more records, it's removed from the response.
        continuationUri:
          type: string
          description: The URI of the next result set batch. If there are no more records, it's removed from the response.
    Members:
      description: The members object which contains the members of the role as arrays of different member types.
      type: object
      properties:
        fabricItemMembers:
          description: 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.
          type: array
          items:
            $ref: '#/components/schemas/FabricItemMember'
        microsoftEntraMembers:
          description: The list of Microsoft Entra ID members.
          type: array
          items:
            $ref: '#/components/schemas/MicrosoftEntraMember'
    ErrorParameter:
      description: A structured parameter providing additional machine-readable context about an error.
      type: object
      properties:
        name:
          type: string
          description: The parameter identifier.
          readOnly: true
        value:
          type: string
          description: The parameter value.
          readOnly: true
        message:
          type: string
          description: A human-readable description of the parameter's meaning.
          readOnly: true