Skip to main content

Object life cycle

All objects and tokens in Vault have a life cycle. This life cycle simplifies your privacy compliance by providing for data minimization with automatic data expiration and retaining expired data with tightly controlled access. Both features are critical parts of all privacy regulations.

Life cycle overview​

The object and token life cycle is based on two principles:

  • Expiration which determines how long an object or token remains active and generally available for use in Vault.
  • Retention which determines how long expired objects and tokens are kept in Vault before they are removed.

This results in objects and tokens existing in one of two states:

  • active: an unexpired object or token.
  • archived: an expired object or token.

Objects and tokens transition through the states as shown in this diagram:

Object life cycleObject life cycle

The events in this life cycle are as follows:

  • create: a user creates an object or token. The item is given an expiration period and enters the active state.
  • expire: an object or token expires. The item enters the archived state.
  • archive: a user archives an object or token. The item enters the archived state.
  • restore: a user sets a new expiration period on an object or token. The item enters the active state.
  • delete: a user calls the deletion action on an object or a token.
  • prune: a user or the background prune job deletes an object or token whose retention period has elapsed.

These events are implemented by the following REST API operations:

The CLI provides similar commands.

Access control​

Access to active objects and tokens is controlled through IAM policy resources without the need for specific options or flags in the REST API and CLI.

Access to archived objects and tokens requires:

  • use of an archive option on the REST API and flag in the CLI.
  • the user to have access to archived resources granted through IAM.

Archived tokens cannot be detokenized.

Cascading expiration and deletion​

Vault provides two types of objects: person objects and data objects. Data objects are usually associated with a person object, for example, details of credit cards owned by a person. The person object and related data objects may also be represented in tokens.

Person objects, data objects, and tokens can have independent expiration periods. However, when a person object expires or is deleted or pruned, Vault also expires or removes any associated data objects and tokens.

Setting expiration and retention periods​

By default, the expiration time is set when an object or token is created using the values specified in the expiration environment variables as follows:

  • for tokens: PVAULT_EXPIRATION_TOKENS.
  • for associated objects (all person objects and any data objects associated with a person object): PVAULT_EXPIRATION_ASSOCIATED_OBJECTS.
  • for unassociated data objects: PVAULT_EXPIRATION_UNASSOCIATED_OBJECTS.

These environment variables have no value by default, meaning that objects and tokens never expire.

These default values can be overridden when creating or updating an object or token using the API or CLI.

The retention period for archived objects and tokens is set with the PVAULT_DB_GC_RETENTION_PERIOD database environment variable. By default, it is set to 30 days.

The prune job​

To help remove archived items at the end of their retention period, Vault includes a prune job that can be run automatically in the background.

The PVAULT_SERVICE_ARCHIVE_PRUNE_INTERVAL service and features environment variable determines how often the prune job runs. By default, this is set to 0, meaning the prune job does not run.

note

If you're using the hosted version of Vault, contact us to set up the prune job.

Objects and tokens can be pruned from Vault on demand using the delete objects and tokens API operation or CLI command.

On this page