Uc Grants

View as Markdown

Control access to Unity Catalog resources

Get Effective PermissionsGET /api/2.1/unity-catalog/effective-permissions/{securable_type}/{securable_full_name}List Effective Privilege AssignmentsGET /api/2.1/unity-catalog/effective-privilege-assignments/{securable_type}/{full_name}List Privilege AssignmentsGET /api/2.1/unity-catalog/privilege-assignments/{securable_type}/{full_name}

Get Effective Permissions

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

Gets the effective permissions for a securable. Includes inherited permissions from any parent securables.

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 effective permissions for the specified principal (user or group) are returned.

max_resultsint32query

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

If not set, all the effective 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 EffectivePrivilegeAssignment 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 token for the next page of results (pagination).

Response

next_page_tokenstring

Opaque token to retrieve the next page of results. Absent if there are no more pages. page_token should be set to this value for the next request (for the next page of results).

privilege_assignmentsarray of object

The privileges conveyed to each principal (either directly or via inheritance)

Show child attributesHide child attributes

principalstring

The principal (user email address or group name).

privilegesarray of object

The privileges conveyed to the principal (either directly or via inheritance).

Show child attributesHide child attributes

privilegestring

The privilege assigned to the principal.

inherited_from_typestring

The type of the object that conveys this privilege via inheritance. This field is omitted when privilege is not inherited (it's assigned to the securable itself).

inherited_from_namestring

The full name of the object that conveys this privilege via inheritance. This field is omitted when privilege is not inherited (it's assigned to the securable itself).

View as Markdown

Response

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

List Effective Privilege Assignments

GET /api/2.1/unity-catalog/effective-privilege-assignments/{securable_type}/{full_name}

Lists the effective privilege assignments for a securable. Includes inherited privileges. Paginated version of Get Effective Permissions API.

API scopes: unity-catalog

Parameters

securable_typestringpath

Type of securable.

full_namestringpath

Full name of securable.

principalstringquery

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

page_sizeint32query

Specifies the maximum number of privilege assignments to return (page length). Every EffectivePrivilegeAssignment present in a single page response is guaranteed to contain all the effective privileges granted on (or inherited by) the requested Securable for the respective principal.

If not set, a server-configured default is used. 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 EffectivePrivilegeAssignment 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

effective_privilege_assignmentsarray of object

The effective privilege assignments for the securable (and optional principal).

Show child attributesHide child attributes

principalstring

The principal (user email address or group name).

privilegesarray of object

The privileges conveyed to the principal (either directly or via inheritance).

Show child attributesHide child attributes

privilegestring

The privilege assigned to the principal.

inherited_from_typestring

The type of the object that conveys this privilege via inheritance. This field is omitted when privilege is not inherited (it's assigned to the securable itself).

inherited_from_namestring

The full name of the object that conveys this privilege via inheritance. This field is omitted when privilege is not inherited (it's assigned to the securable itself).

next_page_tokenstring

Opaque token to retrieve the next page of results. Absent if there are no more pages. page_token should be set to this value for the next request (for the next page of results).

View as Markdown

Response

{
  "effective_privilege_assignments": [
    {
      "principal": "string",
      "privileges": [
        {}
      ]
    }
  ],
  "next_page_token": "string"
}

List Privilege Assignments

GET /api/2.1/unity-catalog/privilege-assignments/{securable_type}/{full_name}

Lists the privilege assignments for a securable. Does not include inherited privileges. Paginated version of Get Permissions API.

API scopes: unity-catalog

Parameters

securable_typestringpath

Type of securable.

full_namestringpath

Full name of securable.

principalstringquery

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

page_sizeint32query

Specifies the maximum number of privilege assignments 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, page length is the server configured value. 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

privilege_assignmentsarray of object

Show child attributesHide child attributes

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

next_page_tokenstring

Opaque token to retrieve the next page of results. Absent if there are no more pages. page_token should be set to this value for the next request (for the next page of results).

View as Markdown

Response

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