# Rotate Recipient Token

Launch stage: 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

## Path parameters

- `name` (string, optional)
  The name of the Recipient.

## Request body

- `existing_token_expire_in_seconds` (int64, optional)
  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.

## Returns

- `name` (string, optional)
  Name of Recipient.
- `authentication_type` (string, optional)
  Possible values: `TOKEN`, `DATABRICKS`, `OIDC_FEDERATION`, `OAUTH_CLIENT_CREDENTIALS`
- `sharing_code` (string, optional)
  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_id` (string, optional)
  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__.
- `owner` (string, optional)
  Username of the recipient owner.
- `comment` (string, optional)
  Description about the recipient.
- `ip_access_list` (object, optional)
  IP Access List
  - `allowed_ip_addresses` (array of string, optional)
    Allowed IP Addresses in CIDR notation. Limit of 100.
- `properties_kvpairs` (object, optional)
  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.
  - `properties` (object, optional)
    A map of key-value properties attached to the securable.
- `expiration_time` (int64, optional)
  Expiration timestamp of the token, in epoch milliseconds.
- `activation_url` (string, optional)
  Full activation url to retrieve the access token.
   It will be empty if the token is already retrieved.
- `activated` (boolean, optional)
  A boolean status field showing whether the Recipient's activation URL has been exercised or not.
- `created_at` (int64, optional)
  Time at which this recipient was created, in epoch milliseconds.
- `created_by` (string, optional)
  Username of recipient creator.
- `tokens` (array of object, optional)
  This field is only present when the __authentication_type__ is **TOKEN**.
  - `id` (string, optional)
    Unique ID of the recipient token.
  - `created_at` (int64, optional)
    Time at which this recipient token was created, in epoch milliseconds.
  - `created_by` (string, optional)
    Username of recipient token creator.
  - `activation_url` (string, optional)
    Full activation URL to retrieve the access token. It will be empty if the token is already retrieved.
  - `expiration_time` (int64, optional)
    Expiration timestamp of the token in epoch milliseconds.
  - `updated_at` (int64, optional)
    Time at which this recipient token was updated, in epoch milliseconds.
  - `updated_by` (string, optional)
    Username of recipient token updater.
- `updated_at` (int64, optional)
  Time at which the recipient was updated, in epoch milliseconds.
- `updated_by` (string, optional)
  Username of recipient updater.
- `cloud` (string, optional)
  Cloud vendor of the recipient's Unity Catalog Metastore.
   This field is only present when the __authentication_type__ is **DATABRICKS**.
- `region` (string, optional)
  Cloud region of the recipient's Unity Catalog Metastore.
   This field is only present when the __authentication_type__ is **DATABRICKS**.
- `metastore_id` (string, optional)
  Unique identifier of recipient's Unity Catalog Metastore.
   This field is only present when the __authentication_type__ is **DATABRICKS**.
- `id` (string, optional)
  [Create,Update:IGN] common - id of the recipient

## Response

```json
{
  "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"
}
```