Sharing

View as Markdown

Configure data sharing with Unity Catalog for providers, recipients, and shares

Get Activation Url InfoGET /api/2.1/unity-catalog/public/data_sharing_activation_info/{activation_url}List Provider Share AssetsGET /api/2.1/data-sharing/providers/{provider_name_arg}/shares/{share_name_arg}List Provider SharesGET /api/2.1/unity-catalog/providers/{provider_name_arg}/sharesList ProvidersGET /api/2.1/unity-catalog/providersList Recipient Share PermissionsGET /api/2.1/unity-catalog/recipients/{name}/share-permissionsList RecipientsGET /api/2.1/unity-catalog/recipientsList Share PermissionsGET /api/2.1/unity-catalog/shares/{name}/permissionsList SharesGET /api/2.1/unity-catalog/sharesRetrieve Access TokenGET /api/2.1/unity-catalog/public/data_sharing_activation/{activation_url}Rotate Recipient TokenPOST /api/2.1/unity-catalog/recipients/{name}/rotate-tokenUpdate Share PermissionsPATCH /api/2.1/unity-catalog/shares/{name}/permissions

Get Activation Url Info GA

GET /api/2.1/unity-catalog/public/data_sharing_activation_info/{activation_url}

Gets an activation URL for a share.

API scopes: sharing

Parameters

activation_urlstringpath

The one time activation url. It also accepts activation token.

View as Markdown

Response

{}

List Provider Share Assets GA

GET /api/2.1/data-sharing/providers/{provider_name_arg}/shares/{share_name_arg}

Get arrays of assets associated with a specified provider's share. The caller is the recipient of the share.

API scopes: sharing

Parameters

provider_name_argstringpath

The name of the provider who owns the share.

share_name_argstringpath

The name of the share.

table_max_resultsint32query

Maximum number of tables to return.

Default: 500

Constraints: <= 500

function_max_resultsint32query

Maximum number of functions to return.

Default: 500

Constraints: <= 500

volume_max_resultsint32query

Maximum number of volumes to return.

Default: 500

Constraints: <= 500

notebook_max_resultsint32query

Maximum number of notebooks to return.

Default: 100

Constraints: <= 100

Response

tablesarray of object

The list of tables in the share.

Show child attributesHide child attributes

namestring

The name of the table.

schemastring

The name of the schema that the table belongs to.

sharestring

The name of the share that the table belongs to.

share_idstring

The id of the share that the table belongs to.

idstring

The id of the table.

commentstring

The comment of the table.

tagsarray of object

The Tags of the table.

Show child attributesHide child attributes

keystring

name of the tag

valuestring

value of the tag associated with the key, could be optional

materialized_table_namestring

The name of a materialized table.

materialization_namespacestring

The catalog and schema of the materialized table

functionsarray of object

The list of functions in the share.

Show child attributesHide child attributes

namestring

The name of the function.

schemastring

The name of the schema that the function belongs to.

sharestring

The name of the share that the function belongs to.

share_idstring

The id of the share that the function belongs to.

idstring

The id of the function.

storage_locationstring

The storage location of the function.

commentstring

The comment of the function.

aliasesarray of object

The aliass of registered model.

Show child attributesHide child attributes

alias_namestring

Name of the alias.

version_numint64

Numeric model version that alias will reference.

tagsarray of object

The tags of the function.

Show child attributesHide child attributes

keystring

name of the tag

valuestring

value of the tag associated with the key, could be optional

securable_kindstring

The securable kind of the function.

Values: SHARED_SECURABLE_KIND_UNSPECIFIED, FUNCTION_STANDARD, FUNCTION_REGISTERED_MODEL, FUNCTION_FEATURE_SPEC

full_data_typestring

The full data type of the function.

data_typestring

The data type of the function.

Values: COLUMN_TYPE_NAME_UNSPECIFIED, BOOLEAN, BYTE, SHORT, INT, LONG, FLOAT, DOUBLE, DATE, TIMESTAMP, STRING, BINARY, DECIMAL, INTERVAL, ARRAY, STRUCT, MAP, CHAR, NULL, USER_DEFINED_TYPE, TIMESTAMP_NTZ, VARIANT, TABLE_TYPE

routine_definitionstring

The routine definition of the function.

input_paramsobject

The function parameter information.

Show child attributesHide child attributes

parametersarray of object

The list of parameters of the function.

Show child attributesHide child attributes

namestring

The name of the parameter.

type_textstring

The type of the parameter in text format.

type_jsonstring

The type of the parameter in JSON format.

type_namestring

The type of the parameter in Enum format.

Values: COLUMN_TYPE_NAME_UNSPECIFIED, BOOLEAN, BYTE, SHORT, INT, LONG, FLOAT, DOUBLE, DATE, TIMESTAMP, STRING, BINARY, DECIMAL, INTERVAL, ARRAY, STRUCT, MAP, CHAR, NULL, USER_DEFINED_TYPE, TIMESTAMP_NTZ, VARIANT, TABLE_TYPE

type_precisionint32

The precision of the parameter type.

type_scaleint32

The scale of the parameter type.

type_interval_typestring

The interval type of the parameter type.

positionint32

The position of the parameter.

parameter_modestring

The mode of the function parameter.

Values: FUNCTION_PARAMETER_MODE_UNSPECIFIED, IN, OUT, INOUT

parameter_typestring

The type of the function parameter.

Values: FUNCTION_PARAMETER_TYPE_UNSPECIFIED, PARAM, COLUMN

parameter_defaultstring

The default value of the parameter.

commentstring

The comment of the parameter.

dependency_listobject

The dependency list of the function.

Show child attributesHide child attributes

dependenciesarray of object

An array of Dependency.

Show child attributesHide child attributes

tableobjectRequired

functionobjectRequired

propertiesstring

The properties of the function.

notebooksarray of object

The list of notebooks in the share.

Show child attributesHide child attributes

namestring

Name of the notebook file.

sharestring

The name of the share that the notebook file belongs to.

share_idstring

The id of the share that the notebook file belongs to.

idstring

The id of the notebook file.

commentstring

The comment of the notebook file.

tagsarray of object

The tags of the notebook file.

Show child attributesHide child attributes

keystring

name of the tag

valuestring

value of the tag associated with the key, could be optional

volumesarray of object

The list of volumes in the share.

Show child attributesHide child attributes

namestring

The name of the volume.

idstring

This id maps to the shared_volume_id in database Recipient needs shared_volume_id for recon to check if this volume is already in recipient's DB or not.

schemastring

The name of the schema that the volume belongs to.

sharestring

The name of the share that the volume belongs to.

share_idstring

/ The id of the share that the volume belongs to.

commentstring

The comment of the volume.

tagsarray of object

The tags of the volume.

Show child attributesHide child attributes

keystring

name of the tag

valuestring

value of the tag associated with the key, could be optional

shareobject

The metadata of the share.

Show child attributesHide child attributes

namestring

idstring

View as Markdown

Response

{
  "tables": [
    {
      "name": "string",
      "schema": "string",
      "share": "string",
      "share_id": "string",
      "id": "string",
      "comment": "string",
      "tags": [
        {}
      ],
      "materialized_table_name": "string",
      "materialization_namespace": "string"
    }
  ],
  "functions": [
    {
      "name": "string",
      "schema": "string",
      "share": "string",
      "share_id": "string",
      "id": "string",
      "storage_location": "string",
      "comment": "string",
      "aliases": [
        {}
      ],
      "tags": [
        {}
      ],
      "securable_kind": "string",
      "full_data_type": "string",
      "data_type": "string",
      "routine_definition": "string",
      "input_params": {},
      "dependency_list": {},
      "properties": "string"
    }
  ],
  "notebooks": [
    {
      "name": "string",
      "share": "string",
      "share_id": "string",
      "id": "string",
      "comment": "string",
      "tags": [
        {}
      ]
    }
  ],
  "volumes": [
    {
      "name": "string",
      "id": "string",
      "schema": "string",
      "share": "string",
      "share_id": "string",
      "comment": "string",
      "tags": [
        {}
      ]
    }
  ],
  "share": {
    "name": "string",
    "id": "string"
  }
}

List Provider Shares GA

GET /api/2.1/unity-catalog/providers/{provider_name_arg}/shares

Gets an array of a specified provider's shares within the metastore where:

• the caller is a metastore admin, or
• the caller is the owner.

API scopes: sharing

Parameters

provider_name_argstringpath

Name of the provider in which to list shares.

max_resultsint32query

Maximum number of shares to return.

• when set to 0, the page length is set to a server configured value (recommended);
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
• when set to a value less than 0, an invalid parameter error is returned;
• If not set, all valid shares are returned (not recommended).
• Note: The number of returned shares might be less than the specified max_results size, even zero. The only definitive indication that no further shares can be fetched is when the next_page_token is unset from the response.

Constraints: <= 1000

page_tokenstringquery

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

Response

sharesarray of object

An array of provider shares.

Show child attributesHide child attributes

namestring

The name of the Provider Share.

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

{
  "shares": [
    {
      "name": "string"
    }
  ],
  "next_page_token": "string"
}

List Providers GA

GET /api/2.1/unity-catalog/providers

Gets an array of available authentication providers. The caller must either be a metastore admin, have the USE_PROVIDER privilege on the providers, or be the owner of the providers. Providers not owned by the caller and for which the caller does not have the USE_PROVIDER privilege are not included in the response. There is no guarantee of a specific ordering of the elements in the array.

API scopes: sharing

Parameters

data_provider_global_metastore_idstringquery

If not provided, all providers will be returned. If no providers exist with this ID, no results will be returned.

max_resultsint32query

Maximum number of providers to return.

• when set to 0, the page length is set to a server configured value (recommended);
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
• when set to a value less than 0, an invalid parameter error is returned;
• If not set, all valid providers are returned (not recommended).
• Note: The number of returned providers might be less than the specified max_results size, even zero. The only definitive indication that no further providers can be fetched is when the next_page_token is unset from the response.

Constraints: <= 1000

page_tokenstringquery

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

Response

providersarray of object

An array of provider information objects.

Show child attributesHide child attributes

namestring

The name of the Provider.

authentication_typestring

Values: TOKEN, DATABRICKS, OIDC_FEDERATION, OAUTH_CLIENT_CREDENTIALS

recipient_profile_strstring

This field is required when the authentication_type is TOKEN, OAUTH_CLIENT_CREDENTIALS or not provided.

commentstring

Description about the provider.

ownerstring

Username of Provider owner.

recipient_profileobject

The recipient profile. This field is only present when the authentication_type is TOKEN or OAUTH_CLIENT_CREDENTIALS.

Show child attributesHide child attributes

share_credentials_versionint32

The version number of the recipient's credentials on a share.

endpointstring

The endpoint for the share to be used by the recipient.

bearer_tokenstring

The token used to authorize the recipient.

created_atint64

Time at which this Provider was created, in epoch milliseconds.

created_bystring

Username of Provider creator.

updated_atint64

Time at which this Provider was created, in epoch milliseconds.

updated_bystring

Username of user who last modified Provider.

cloudstring

Cloud vendor of the provider's UC metastore. This field is only present when the authentication_type is DATABRICKS.

regionstring

Cloud region of the provider's UC metastore. This field is only present when the authentication_type is DATABRICKS.

metastore_idstring

UUID of the provider's UC metastore. This field is only present when the authentication_type is DATABRICKS.

data_provider_global_metastore_idstring

The global UC metastore id of the data provider. This field is only present when the authentication_type is DATABRICKS. The identifier is of format cloud:region:metastore-uuid.

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

{
  "providers": [
    {
      "name": "string",
      "authentication_type": "string",
      "recipient_profile_str": "string",
      "comment": "string",
      "owner": "string",
      "recipient_profile": {},
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "cloud": "string",
      "region": "string",
      "metastore_id": "string",
      "data_provider_global_metastore_id": "string"
    }
  ],
  "next_page_token": "string"
}

List Recipient Share Permissions GA

GET /api/2.1/unity-catalog/recipients/{name}/share-permissions

Gets the share permissions for the specified Recipient. The caller must have the USE_RECIPIENT privilege on the metastore or be the owner of the Recipient.

API scopes: sharing

Parameters

namestringpath

The name of the Recipient.

max_resultsint32query

Maximum number of permissions to return.

• when set to 0, the page length is set to a server configured value (recommended);
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
• when set to a value less than 0, an invalid parameter error is returned;
• If not set, all valid permissions are returned (not recommended).
• Note: The number of returned permissions might be less than the specified max_results size, even zero. The only definitive indication that no further permissions can be fetched is when the next_page_token is unset from the response.

Constraints: <= 1000

page_tokenstringquery

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

Response

permissions_outarray of object

An array of data share permissions for a recipient.

Show child attributesHide child attributes

share_namestring

The share name.

privilege_assignmentsarray of object

The privileges assigned to the principal.

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

{
  "permissions_out": [
    {
      "share_name": "string",
      "privilege_assignments": [
        {}
      ]
    }
  ],
  "next_page_token": "string"
}

List Recipients GA

GET /api/2.1/unity-catalog/recipients

Gets an array of all share recipients within the current metastore where:

• the caller is a metastore admin, or
• the caller is the owner. There is no guarantee of a specific ordering of the elements in the array.

API scopes: sharing

Parameters

data_recipient_global_metastore_idstringquery

If not provided, all recipients will be returned. If no recipients exist with this ID, no results will be returned.

max_resultsint32query

Maximum number of recipients to return.

• when set to 0, the page length is set to a server configured value (recommended);
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
• when set to a value less than 0, an invalid parameter error is returned;
• If not set, all valid recipients are returned (not recommended).
• Note: The number of returned recipients might be less than the specified max_results size, even zero. The only definitive indication that no further recipients can be fetched is when the next_page_token is unset from the response.

Constraints: <= 1000

page_tokenstringquery

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

Response

recipientsarray of object

An array of recipient information objects.

Show child attributesHide child attributes

namestring

Name of Recipient.

authentication_typestring

Values: TOKEN, DATABRICKS, OIDC_FEDERATION, OAUTH_CLIENT_CREDENTIALS

sharing_codestring

The one-time sharing code provided by the data recipient. This field is only present when the authentication_type is DATABRICKS.

data_recipient_global_metastore_idstring

The global Unity Catalog metastore id provided by the data recipient. This field is only present when the authentication_type is DATABRICKS. The identifier is of format cloud:region:metastore-uuid.

ownerstring

Username of the recipient owner.

commentstring

Description about the recipient.

ip_access_listobject

IP Access List

Show child attributesHide child attributes

allowed_ip_addressesarray of string

Allowed IP Addresses in CIDR notation. Limit of 100.

properties_kvpairsobject

Recipient properties as map of string key-value pairs. When provided in update request, the specified properties will override the existing properties. To add and remove properties, one would need to perform a read-modify-write.

Show child attributesHide child attributes

propertiesobject

A map of key-value properties attached to the securable.

expiration_timeint64

Expiration timestamp of the token, in epoch milliseconds.

activation_urlstring

Full activation url to retrieve the access token. It will be empty if the token is already retrieved.

activatedboolean

A boolean status field showing whether the Recipient's activation URL has been exercised or not.

created_atint64

Time at which this recipient was created, in epoch milliseconds.

created_bystring

Username of recipient creator.

tokensarray of object

This field is only present when the authentication_type is TOKEN.

Show child attributesHide child attributes

idstring

Unique ID of the recipient token.

created_atint64

Time at which this recipient token was created, in epoch milliseconds.

created_bystring

Username of recipient token creator.

activation_urlstring

Full activation URL to retrieve the access token. It will be empty if the token is already retrieved.

expiration_timeint64

Expiration timestamp of the token in epoch milliseconds.

updated_atint64

Time at which this recipient token was updated, in epoch milliseconds.

updated_bystring

Username of recipient token updater.

updated_atint64

Time at which the recipient was updated, in epoch milliseconds.

updated_bystring

Username of recipient updater.

cloudstring

Cloud vendor of the recipient's Unity Catalog Metastore. This field is only present when the authentication_type is DATABRICKS.

regionstring

Cloud region of the recipient's Unity Catalog Metastore. This field is only present when the authentication_type is DATABRICKS.

metastore_idstring

Unique identifier of recipient's Unity Catalog Metastore. This field is only present when the authentication_type is DATABRICKS.

idstring

[Create,Update:IGN] common - id of the recipient

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

{
  "recipients": [
    {
      "name": "string",
      "authentication_type": "string",
      "sharing_code": "string",
      "data_recipient_global_metastore_id": "string",
      "owner": "string",
      "comment": "string",
      "ip_access_list": {},
      "properties_kvpairs": {},
      "expiration_time": 0,
      "activation_url": "string",
      "activated": true,
      "created_at": 0,
      "created_by": "string",
      "tokens": [
        {}
      ],
      "updated_at": 0,
      "updated_by": "string",
      "cloud": "string",
      "region": "string",
      "metastore_id": "string",
      "id": "string"
    }
  ],
  "next_page_token": "string"
}

List Share Permissions GA

GET /api/2.1/unity-catalog/shares/{name}/permissions

Gets the permissions for a data share from the metastore. The caller must have the USE_SHARE privilege on the metastore or be the owner of the share.

API scopes: sharing

Parameters

namestringpath

The name of the share.

max_resultsint32query

Maximum number of permissions to return.

• when set to 0, the page length is set to a server configured value (recommended);
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
• when set to a value less than 0, an invalid parameter error is returned;
• If not set, all valid permissions are returned (not recommended).
• Note: The number of returned permissions might be less than the specified max_results size, even zero. The only definitive indication that no further permissions can be fetched is when the next_page_token is unset from the response.

Constraints: <= 1000

page_tokenstringquery

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

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 assigned to each principal

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

View as Markdown

Response

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

List Shares GA

GET /api/2.1/unity-catalog/shares

Gets an array of data object shares from the metastore. If the caller has the USE_SHARE privilege on the metastore, all shares are returned. Otherwise, only shares owned by the caller are returned. There is no guarantee of a specific ordering of the elements in the array.

API scopes: sharing

Parameters

max_resultsint32query

Maximum number of shares to return.

• when set to 0, the page length is set to a server configured value (recommended);
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
• when set to a value less than 0, an invalid parameter error is returned;
• If not set, all valid shares are returned (not recommended).
• Note: The number of returned shares might be less than the specified max_results size, even zero. The only definitive indication that no further shares can be fetched is when the next_page_token is unset from the response.

Constraints: <= 1000

page_tokenstringquery

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

Response

sharesarray of object

An array of data share information objects.

Show child attributesHide child attributes

namestring

Name of the share.

ownerstring

Username of current owner of share.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for the share.

objectsarray of object

A list of shared data objects within the share.

Show child attributesHide child attributes

namestring

A fully qualified name that uniquely identifies a data object. For example, a table's fully qualified name is in the format of <catalog>.<schema>.<table>,

data_object_typestring

The type of the data object.

added_atint64

The time when this data object is added to the share, in epoch milliseconds.

added_bystring

Username of the sharer.

commentstring

A user-provided comment when adding the data object to the share.

shared_asstring

A user-provided alias name for table-like data objects within the share.

Use this field for table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE). For non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION), use string_shared_as instead.

Important: For non-table objects, this field must be omitted entirely.

Format: Must be a 2-part name <schema_name>.<table_name> (e.g., "sales_schema.orders_table")

• Both schema and table names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part
• Do not include the catalog name (use 2 parts, not 3)

Behavior:

• If not provided, the service automatically generates the alias as <schema>.<table> from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The shared_as name must be unique within the share

Examples:

• Valid: "analytics_schema.customer_view"
• Invalid: "catalog.analytics_schema.customer_view" (3 parts not allowed)
• Invalid: "analytics-schema.customer-view" (hyphens not allowed)

cdf_enabledboolean

Whether to enable cdf or indicate if cdf is enabled on the shared object.

history_data_sharing_statusstring

Whether to enable or disable sharing of data history. If not specified, the default is DISABLED.

Values: DISABLED, ENABLED

start_versionint64

The start version associated with the object. This allows data providers to control the lowest object version that is accessible by clients. If specified, clients can query snapshots or changes for versions >= start_version. If not specified, clients can only query starting from the version of the object at the time it was added to the share.

NOTE: The start_version should be <= the current version of the object.

statusstring

One of: ACTIVE, PERMISSION_DENIED.

Values: ACTIVE, PERMISSION_DENIED

contentstring

The content of the notebook file when the data object type is NOTEBOOK_FILE. This should be base64 encoded. Required for adding a NOTEBOOK_FILE, optional for updating, ignored for other types.

string_shared_asstring

A user-provided alias name for non-table data objects within the share.

Use this field for non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION). For table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE), use shared_as instead.

Important: For table-like objects, this field must be omitted entirely.

Format:

• For VOLUME: Must be a 2-part name <schema_name>.<volume_name> (e.g., "data_schema.ml_models")
• For FUNCTION: Must be a 2-part name <schema_name>.<function_name> (e.g., "udf_schema.calculate_tax")
• For MODEL: Must be a 2-part name <schema_name>.<model_name> (e.g., "models.prediction_model")
• For NOTEBOOK_FILE: Should be the notebook file name (e.g., "analysis_notebook.py")
• All names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part

Behavior:

• If not provided, the service automatically generates the alias from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The string_shared_as name must be unique for objects of the same type within the share

Examples:

• Valid for VOLUME: "data_schema.training_data"
• Valid for FUNCTION: "analytics.calculate_revenue"
• Invalid: "catalog.data_schema.training_data" (3 parts not allowed for volumes)
• Invalid: "data-schema.training-data" (hyphens not allowed)

partitionsarray of object

Array of partitions for the shared data.

Show child attributesHide child attributes

valuesarray of object

An array of partition values.

created_atint64

Time at which this share was created, in epoch milliseconds.

created_bystring

Username of share creator.

updated_atint64

Time at which this share was updated, in epoch milliseconds.

updated_bystring

Username of share updater.

storage_locationstring

Storage Location URL (full path) for the share.

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

{
  "shares": [
    {
      "name": "string",
      "owner": "string",
      "comment": "string",
      "storage_root": "string",
      "objects": [
        {}
      ],
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "storage_location": "string"
    }
  ],
  "next_page_token": "string"
}

Retrieve Access Token GA

GET /api/2.1/unity-catalog/public/data_sharing_activation/{activation_url}

Retrieve access token with an activation url. This is a public API without any authentication.

API scopes: sharing

Parameters

activation_urlstringpath

The one time activation url. It also accepts activation token.

Response

shareCredentialsVersionint32

These field names must follow the delta sharing protocol.

bearerTokenstring

The token used to authorize the recipient.

endpointstring

The endpoint for the share to be used by the recipient.

expirationTimestring

Expiration timestamp of the token in epoch milliseconds.

View as Markdown

Response

{
  "shareCredentialsVersion": 0,
  "bearerToken": "string",
  "endpoint": "string",
  "expirationTime": "string"
}

Rotate Recipient Token GA

POST /api/2.1/unity-catalog/recipients/{name}/rotate-token

Refreshes the specified recipient's delta sharing authentication token with the provided token info. The caller must be the owner of the recipient.

API scopes: sharing

Parameters

namestringpath

The name of the Recipient.

Request body

existing_token_expire_in_secondsint64

The expiration time of the bearer token in ISO 8601 format. This will set the expiration_time of existing token only to a smaller timestamp, it cannot extend the expiration_time. Use 0 to expire the existing token immediately, negative number will return an error.

Response

namestring

Name of Recipient.

authentication_typestring

Values: TOKEN, DATABRICKS, OIDC_FEDERATION, OAUTH_CLIENT_CREDENTIALS

sharing_codestring

The one-time sharing code provided by the data recipient. This field is only present when the authentication_type is DATABRICKS.

data_recipient_global_metastore_idstring

The global Unity Catalog metastore id provided by the data recipient. This field is only present when the authentication_type is DATABRICKS. The identifier is of format cloud:region:metastore-uuid.

ownerstring

Username of the recipient owner.

commentstring

Description about the recipient.

ip_access_listobject

IP Access List

Show child attributesHide child attributes

allowed_ip_addressesarray of string

Allowed IP Addresses in CIDR notation. Limit of 100.

properties_kvpairsobject

Recipient properties as map of string key-value pairs. When provided in update request, the specified properties will override the existing properties. To add and remove properties, one would need to perform a read-modify-write.

Show child attributesHide child attributes

propertiesobject

A map of key-value properties attached to the securable.

expiration_timeint64

Expiration timestamp of the token, in epoch milliseconds.

activation_urlstring

Full activation url to retrieve the access token. It will be empty if the token is already retrieved.

activatedboolean

A boolean status field showing whether the Recipient's activation URL has been exercised or not.

created_atint64

Time at which this recipient was created, in epoch milliseconds.

created_bystring

Username of recipient creator.

tokensarray of object

This field is only present when the authentication_type is TOKEN.

Show child attributesHide child attributes

idstring

Unique ID of the recipient token.

created_atint64

Time at which this recipient token was created, in epoch milliseconds.

created_bystring

Username of recipient token creator.

activation_urlstring

Full activation URL to retrieve the access token. It will be empty if the token is already retrieved.

expiration_timeint64

Expiration timestamp of the token in epoch milliseconds.

updated_atint64

Time at which this recipient token was updated, in epoch milliseconds.

updated_bystring

Username of recipient token updater.

updated_atint64

Time at which the recipient was updated, in epoch milliseconds.

updated_bystring

Username of recipient updater.

cloudstring

Cloud vendor of the recipient's Unity Catalog Metastore. This field is only present when the authentication_type is DATABRICKS.

regionstring

Cloud region of the recipient's Unity Catalog Metastore. This field is only present when the authentication_type is DATABRICKS.

metastore_idstring

Unique identifier of recipient's Unity Catalog Metastore. This field is only present when the authentication_type is DATABRICKS.

idstring

[Create,Update:IGN] common - id of the recipient

View as Markdown

Request

{
  "existing_token_expire_in_seconds": 0
}

Response

{
  "name": "string",
  "authentication_type": "string",
  "sharing_code": "string",
  "data_recipient_global_metastore_id": "string",
  "owner": "string",
  "comment": "string",
  "ip_access_list": {
    "allowed_ip_addresses": [
      "string"
    ]
  },
  "properties_kvpairs": {
    "properties": {}
  },
  "expiration_time": 0,
  "activation_url": "string",
  "activated": true,
  "created_at": 0,
  "created_by": "string",
  "tokens": [
    {
      "id": "string",
      "created_at": 0,
      "created_by": "string",
      "activation_url": "string",
      "expiration_time": 0,
      "updated_at": 0,
      "updated_by": "string"
    }
  ],
  "updated_at": 0,
  "updated_by": "string",
  "cloud": "string",
  "region": "string",
  "metastore_id": "string",
  "id": "string"
}

Update Share Permissions GA

PATCH /api/2.1/unity-catalog/shares/{name}/permissions

Updates the permissions for a data share in the metastore. The caller must have both the USE_SHARE and SET_SHARE_PERMISSION privileges on the metastore, or be the owner of the share.

For new recipient grants, the user must also be the owner of the recipients. recipient revocations do not require additional privileges.

API scopes: sharing

Parameters

namestringpath

The name of the share.

Request body

omit_permissions_listboolean

Optional. Whether to return the latest permissions list of the share in the response.

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

privilege_assignmentsarray of object

The privileges assigned to each principal

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

View as Markdown

Request

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

Response

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