Recipient

View as Markdown

Get a share recipientGET /api/2.1/unity-catalog/recipients/{name}List share recipientsGET /api/2.1/unity-catalog/recipientsCreate a share recipientPOST /api/2.1/unity-catalog/recipientsUpdate a share recipientPATCH /api/2.1/unity-catalog/recipients/{name_arg}Delete a share recipientDELETE /api/2.1/unity-catalog/recipients/{name}Rotate a tokenPOST /api/2.1/unity-catalog/recipients/{name}/rotate-tokenGet recipient share permissionsGET /api/2.1/unity-catalog/recipients/{name}/share-permissions

RecipientInfo object

namestring

Name of Recipient.

authentication_typestring

The delta sharing authentication type.

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_urlstringDeprecatedOutput only

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

activatedbooleanDeprecatedOutput only

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

created_atint64Output only

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

created_bystringOutput only

Username of recipient creator.

tokensarray of objectOutput only

This field is only present when the authentication_type is TOKEN.

Show child attributesHide child attributes

idstringOutput only

Unique ID of the recipient token.

created_atint64Output only

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

created_bystringOutput only

Username of recipient token creator.

activation_urlstringOutput only

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

expiration_timeint64Output only

Expiration timestamp of the token in epoch milliseconds.

updated_atint64Output only

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

updated_bystringOutput only

Username of recipient token updater.

updated_atint64Output only

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

updated_bystringOutput only

Username of recipient updater.

cloudstringOutput only

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

regionstringOutput only

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

metastore_idstringOutput only

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

idstringOutput only

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

View as Markdown

The RecipientInfo object

{
  "name": "string",
  "authentication_type": "TOKEN",
  "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"
}

Get a share recipient GA

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

Gets a share recipient from the metastore. The caller must be one of:

• A user with USE_RECIPIENT privilege on the metastore
• The owner of the share recipient
• A metastore admin

API scopes: sharing

Parameters

namestringRequiredpath

Name of the recipient.

Response

Returns the RecipientInfo object.

View as Markdown

Response

{
  "name": "string",
  "authentication_type": "TOKEN",
  "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"
}

List share 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_resultsint32<= 1000query

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.

page_tokenstringquery

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

Response

Returns a list of RecipientInfo objects.

View as Markdown

Response

{
  "recipients": [
    {
      "name": "string",
      "authentication_type": "TOKEN",
      "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"
}

Create a share recipient GA

POST /api/2.1/unity-catalog/recipients

Creates a new recipient with the delta sharing authentication type in the metastore. The caller must be a metastore admin or have the CREATE_RECIPIENT privilege on the metastore.

API scopes: sharing

Request body

namestring

Name of Recipient.

authentication_typestring

The delta sharing authentication type.

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

propertiesobjectRequired

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

expiration_timeint64

Expiration timestamp of the token, in epoch milliseconds.

Response

Returns the RecipientInfo object.

View as Markdown

Request

{
  "name": "string",
  "authentication_type": "TOKEN",
  "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
}

Response

{
  "name": "string",
  "authentication_type": "TOKEN",
  "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 a share recipient GA

PATCH /api/2.1/unity-catalog/recipients/{name_arg}

Updates an existing recipient in the metastore. The caller must be a metastore admin or the owner of the recipient. If the recipient name will be updated, the user must be both a metastore admin and the owner of the recipient.

API scopes: sharing

Parameters

name_argstringRequiredpath

Name of the recipient.

Request body

new_namestring

New name for the recipient. .

namestring

Name of Recipient.

authentication_typestring

The delta sharing authentication type.

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

propertiesobjectRequired

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

expiration_timeint64

Expiration timestamp of the token, in epoch milliseconds.

Response

Returns the RecipientInfo object.

View as Markdown

Request

{
  "new_name": "string",
  "name": "string",
  "authentication_type": "TOKEN",
  "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
}

Response

{
  "name": "string",
  "authentication_type": "TOKEN",
  "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"
}

Delete a share recipient GA

DELETE /api/2.1/unity-catalog/recipients/{name}

Deletes the specified recipient from the metastore. The caller must be the owner of the recipient.

API scopes: sharing

Parameters

namestringRequiredpath

Name of the recipient.

View as Markdown

Response

{}

Rotate a 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

namestringRequiredpath

The name of the Recipient.

Request body

existing_token_expire_in_secondsint64Required

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

Returns the RecipientInfo object.

View as Markdown

Request

{
  "existing_token_expire_in_seconds": 0
}

Response

{
  "name": "string",
  "authentication_type": "TOKEN",
  "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"
}

Get 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

namestringRequiredpath

The name of the Recipient.

max_resultsint32<= 1000query

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.

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"
}