Privilege Assignment

PrivilegeAssignment object

principalstring: The principal (user email address or group name). For deleted principals, principal is empty while principal_id is populated.

privilegesarray of string: The privileges assigned to the principal.
Example: SELECT

Get

GET /api/2.1/unity-catalog/permissions/{securable_type}/{securable_full_name}

Gets the permissions for a securable. Does not include inherited permissions.

NOTE: we recommend using max_results=0 to use the paginated version of this API. Unpaginated calls will be deprecated soon.

PAGINATION BEHAVIOR: When using pagination (max_results >= 0), a page may contain zero results while still providing a next_page_token. Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

Parameters

securable_typestringpath: Type of securable.

securable_full_namestringpath: Full name of securable.

principalstringquery: If provided, only the permissions for the specified principal (user or group) are returned.

max_resultsint32query

Specifies the maximum number of privileges to return (page length). Every PrivilegeAssignment present in a single page response is guaranteed to contain all the privileges granted on the requested Securable for the respective principal.

If not set, all the permissions are returned. If set to

lesser than 0: invalid parameter error
0: page length is set to a server configured value
lesser than 150 but greater than 0: invalid parameter error (this is to ensure that server is able to return at least one complete PrivilegeAssignment in a single page response)
greater than (or equal to) 150: page length is the minimum of this value and a server configured value

page_tokenstringquery: Opaque pagination token to go to next page based on previous query.

Response

Returns a list of PrivilegeAssignment objects.

Update

PATCH /api/2.1/unity-catalog/permissions/{securable_type}/{securable_full_name}

Updates the permissions for a securable.

API scopes: unity-catalog

Parameters

securable_typestringpath: Type of securable.

securable_full_namestringpath: Full name of securable.

Request body

omit_permissions_in_responseboolean: Optional, default false. Specifies whether all the permissions should be returned in the response.
Default: false

changesarray of object

Array of permissions change objects.

Show child attributesHide child attributes

principalstring: The principal whose privileges we are changing. Only one of principal or principal_id should be specified, never both at the same time.

addarray of string: The set of privileges to add.

removearray of string: The set of privileges to remove.

Response

Returns a list of PrivilegeAssignment objects.

View as Markdown

Request

{
  "omit_permissions_in_response": true,
  "changes": [
    {
      "principal": "string",
      "add": [
        "string"
      ],
      "remove": [
        "string"
      ]
    }
  ]
}

Response

{
  "privilege_assignments": [
    {
      "principal": "string",
      "privileges": "SELECT"
    }
  ]
}