> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retention Policies

export const Link = ({href, children, className, ...props}) => {
  const localizedHref = href;
  return <a href={localizedHref} className={className} {...props}>
      {children}
    </a>;
};

A retention policy blocks permanent deletion of content for a specified amount
of time. Admins can create retention policies and then assign them to
specific folders or their entire enterprise. Retention policies can be used to
keep data for as long as is needed, and then automatically delete the content
permanently when the data can no longer be legally held.

<Info>
  Retention Policies are a feature of the [Box Governance][governance] package,
  which can be added on to any Business Plus or Enterprise account.
</Info>

## Policies, Assignments, and Retentions

Working with Retention Policies requires a developer to work with three
distinct resources.

* **Policies:**  A <Link href="/reference/resources/retention-policy">Retention Policy</Link> describes the general behavior of the retention policy. It determines how long a retention should stay in place, if it can be extended, and what happens when the retention policy ends.
* **Assignments:** A <Link href="/reference/resources/retention-policy-assignment">Retention Policy Assignment</Link> is a relation between a policy and folder or enterprise. Creating an assignment puts a retention on all the file versions that belong to that folder or enterprise. For example, if an assignment is created on a folder the policy is applied to all file versions within that folder.
* **Retentions**: A <Link href="/reference/resources/file-version-retention">File Version Retention</Link> represents all the policies that are assigned to a specific file version. Note that every file version can have a maximum of one file version retention and that this resource contains a list of every assigned policy.

<Warning>
  The <Link href="/reference/resources/file-version-retention">file version retention</Link> section of the Box API
  is now deprecated. Instead, you can use <Link href="/reference/get-retention-policy-assignments-id-files-under-retention">files under retention</Link> or
  <Link href="/reference/get-retention-policy-assignments-id-file-versions-under-retention">file versions under retention</Link> endpoints.
</Warning>

## File Deletion with Retention Policies

Files under retention can be deleted from folders, but they will be retained in
the trash until the retention expires. When the retention expires,
you can choose to have the content automatically deleted or for the policy to be
removed.

## Extend Retention for a File

Files under retention can have their retention date extended by
<Link href="/reference/put-files-id/#param-disposition_at">updating</Link> the `disposition_at` field's value with a future
date. Once the date has been extended, it cannot be reverted or changed to be
prior to the new date.

## Required Scopes

Before using any of the Retention Policy APIs, an application must have the following <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link> enabled:

* <Link href="/guides/api-calls/permissions-and-errors/scopes#manage-retention-policies">Manage Retention Policies</Link>, available in the Developer Console under **Configuration** > **Application Scopes**
* <Link href="/guides/api-calls/permissions-and-errors/scopes#global-content-manager-gcm">Global Content Manager (GCM)</Link>, enabled by contacting customer support

[governance]: https://www.box.com/security/governance-and-compliance