[Overview](https://docs.cloud.google.com/storage/docs/soft-delete.md.txt)
[Usage](https://docs.cloud.google.com/storage/docs/use-soft-deleted-objects.md.txt)

This page describes how to set and manage [soft delete policies](https://docs.cloud.google.com/storage/docs/soft-delete.md.txt#soft-delete-policy).
You can enable soft delete on a bucket by setting a soft delete policy.
You can also update the retention duration for a bucket and check the status of
existing policies.

For steps to disable soft delete, see
[Disable soft delete](https://docs.cloud.google.com/storage/docs/disable-soft-delete.md.txt).

To learn how to list and restore soft-deleted objects, see
[Use soft-deleted objects](https://docs.cloud.google.com/storage/docs/use-soft-deleted-objects.md.txt). To learn how to list and restore
soft-deleted buckets, see [Use soft-deleted buckets](https://docs.cloud.google.com/storage/docs/use-soft-deleted-buckets.md.txt).

## Required roles


To get the permissions that
you need to enable and manage soft delete policies,

ask your administrator to grant you the
[Storage Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/storage.md.txt#storage.admin) (`roles/storage.admin`) IAM role on the bucket or the project that contains the bucket.


This predefined role contains

the permissions required to enable and manage soft delete policies. To see the exact permissions that are
required, expand the **Required permissions** section:


#### Required permissions

The following permissions are required to enable and manage soft delete policies:

- `storage.buckets.get`
- `storage.buckets.update`
- `storage.buckets.list` (this permission is only required if you plan to use the Google Cloud console to perform the instructions on this page)

For information about granting roles, see
[Set and manage IAM policies on buckets](https://docs.cloud.google.com/storage/docs/access-control/using-iam-permissions.md.txt) or [Manage access to projects](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

## Edit a bucket's soft delete retention duration

When you edit a bucket's soft delete retention duration, the updated
retention duration applies only to objects or buckets that you delete after the
updated soft delete policy takes effect. Existing soft-deleted objects
aren't affected by updates made to the soft delete policy and are retained
for the duration that was in effect when they were deleted.

Use the following instructions to edit a bucket's soft delete
retention duration:

### Console

1. In the Google Cloud console, go to the Cloud Storage **Buckets** page.  

   [Go to Buckets](https://console.cloud.google.com/storage/browser)
2. In the list of buckets, click the name of the bucket whose
   soft delete policy you want to edit.

3. Click the **Protection** tab.

4. In the **Soft delete policy (for data recovery)** section, do the
   following:

   1. Click **Edit**.

   2. In the **Set a soft delete policy** dialog, specify a
      [soft delete retention duration](https://docs.cloud.google.com/storage/docs/soft-delete.md.txt#retention-duration) by choosing a unit
      of time and a length of time.

   3. Click **Save**.

To learn how to get detailed error information about failed Cloud Storage
operations in the Google Cloud console, see
[Troubleshooting](https://docs.cloud.google.com/storage/docs/troubleshooting.md.txt#trouble-console).

### Command line

To add or edit the soft delete retention duration on a bucket, use
the [`gcloud storage buckets update`](https://docs.cloud.google.com/sdk/gcloud/reference/storage/buckets/update) command with the
`--soft-delete-duration` flag:

```
gcloud storage buckets update gs://BUCKET_NAME --soft-delete-duration=SOFT_DELETE_DURATION
```

Replace the following:

- `BUCKET_NAME`: the name of the bucket. For
  example, `my-bucket`.

- `SOFT_DELETE_DURATION`: the
  [soft delete retention duration](https://docs.cloud.google.com/storage/docs/soft-delete.md.txt#retention-duration).

  - The unit `s` represents seconds.
  - The unit `d` represents days.
  - The unit `m` represents months.

  For example:
  - `7d43200s` sets a retention duration of seven and a half days
    (7 days and 43,200 seconds).

  - `2w1d` sets a retention duration of two weeks and one day.

### REST APIs

### JSON API

1. Have gcloud CLI [installed and initialized](https://docs.cloud.google.com/sdk/docs/install), which lets
   you generate an access token for the `Authorization` header.

2. Create a JSON file that contains the following information:

   ```json
   {
     "softDeletePolicy": {
       "retentionDurationSeconds": "TIME_IN_SECONDS"
     }
   }
   ```

   Replace `TIME_IN_SECONDS` with the amount of
   time in seconds you want to set the
   [soft delete retention duration](https://docs.cloud.google.com/storage/docs/soft-delete.md.txt#retention-duration) to. For
   example, `2678400` for 2,678,400 seconds (31 days).
3. Use [`cURL`](http://curl.haxx.se/) to call the [JSON API](https://docs.cloud.google.com/storage/docs/json_api.md.txt) with a
   [`PATCH` Bucket](https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/patch.md.txt) request:

   ```
   curl -X PATCH --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME"
   ```

   Where:
   - `JSON_FILE_NAME` is the path for the JSON file that you created in Step 2.
   - `BUCKET_NAME` is the name of the relevant bucket. For example, `my-bucket`.

## Check whether soft delete is enabled on a bucket

### Console

1. In the Google Cloud console, go to the Cloud Storage **Buckets** page.  

   [Go to Buckets](https://console.cloud.google.com/storage/browser)
2. In the list of buckets, click the name of the bucket whose
   soft delete policy you want to check.

3. Click the **Protection** tab.

   The status displays in the **Soft delete policy (for data recovery)**
   section.


To learn how to get detailed error information about failed Cloud Storage
operations in the Google Cloud console, see
[Troubleshooting](https://docs.cloud.google.com/storage/docs/troubleshooting.md.txt#trouble-console).

### Command line

To check the soft delete policy status of a bucket, use the
[`gcloud storage buckets describe`](https://docs.cloud.google.com/sdk/gcloud/reference/storage/buckets/describe) command:

```
gcloud storage buckets describe gs://BUCKET_NAME --format="default(soft_delete_policy)"
```

Replace `BUCKET_NAME` with the name of the bucket. For
example, `my-bucket`.

### REST APIs

### JSON API

1. Have gcloud CLI [installed and initialized](https://docs.cloud.google.com/sdk/docs/install), which lets
   you generate an access token for the `Authorization` header.

2. Use [`cURL`](http://curl.haxx.se/) to call the [JSON API](https://docs.cloud.google.com/storage/docs/json_api.md.txt) with a
   [`GET` Bucket](https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/get.md.txt) request:

   ```
   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=softDeletePolicy"
   ```

   Replace `BUCKET_NAME` with the name of the
   relevant bucket. For example, `my-bucket`.

## What's next

- Learn how to [use soft-deleted objects](https://docs.cloud.google.com/storage/docs/use-soft-deleted-objects.md.txt).
- Learn how to [use soft-deleted buckets](https://docs.cloud.google.com/storage/docs/use-soft-deleted-buckets.md.txt).
- Learn how to [disable soft delete](https://docs.cloud.google.com/storage/docs/disable-soft-delete.md.txt).