diff --git a/website/content/api-docs/secret/transform.mdx b/website/content/api-docs/secret/transform.mdx index 2b71a4d7f94d..23a1e8a10acf 100644 --- a/website/content/api-docs/secret/transform.mdx +++ b/website/content/api-docs/secret/transform.mdx @@ -1629,7 +1629,7 @@ transformations. of the URL. - `value` `(string: )` – - Specifies the token to test for whether it has a valid tokenization. + Specifies the plaintext to attempt to find the issued token. - `expiration` `(string: "")` - The precise expiration of the token. If omitted, this specifically searches for tokens with no expiration. If the string @@ -1709,6 +1709,162 @@ $ curl \ } ``` +## Delete token + +This endpoint deletes a token from storage, when given the token. +This endpoint is only valid for tokenization transformations. + +| Method | Path | +| :------- | :----------------------------- | +| `DELETE` | `/transform/tokens/:role_name` | + +### Parameters + +- `role_name` `(string: )` – + Specifies the role name to use for this operation. This is specified as part + of the URL. + +- `token` `(string: )` – + The token value to delete. + +- `transformation` `(string)` – + Specifies the transformation within the role that should be used for this + lookup operation. If a single transformation exists for role, this parameter + may be skipped and will be inferred. If multiple transformations exist, one + must be specified. + +- `reference` `(string: "")` - + A user-supplied string that will be present in the `reference` field on the + corresponding `batch_results` item in the response, to assist in understanding + which result corresponds to a particular input. Only valid on batch requests + when using `batch_input` below. + +- `batch_input` `(array: nil)` - + Specifies a list of items to be decoded in a single batch. When this + parameter is set, the `value`, `transformation`, and `reference` parameters are + ignored. Instead, the aforementioned parameters should be provided within + each object in the list. In addition, batched requests can add the `reference` + field described above. + + ```json + [ + { + "token": "AHLdmFvTRknMBgrNSy6Ba7xJxG28KkZeHKqxGJ7e45G3V9UbcUr6gdv83ozwRRQwLfJgyHZvfa9rh7kU9xJXVdY", + "transformation": "ccn-tokenization" + } + ] + ``` + +### Sample payload + +```json +{ + "token": "AHLdmFvTRknMBgrNSy6Ba7xJxG28KkZeHKqxGJ7e45G3V9UbcUr6gdv83ozwRRQwLfJgyHZvfa9rh7kU9xJXVdY", + "transformation": "ccn-tokenization" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + --data @payload.json \ + http://127.0.0.1:8200/v1/transform/tokens/example-role +``` + +## Delete token by plaintext + +This endpoint deletes tokens given a plaintext and as needed an +expiration or range of expirations. This operation is only supported +if the transformation is configured as 'convergent', or if the mapping +mode is exportable and the storage backend is external. Tokens may be +deleted without specifying expiration if the issued token had none, +using an explicit expiration, an expiration value of "any", or with a range +of acceptable expiration times. This endpoint is only valid for tokenization +transformations. + +| Method | Path | +| :------- | :-------------------------------- | +| `DELETE` | `/transform/tokenized/:role_name` | + +### Parameters + +- `role_name` `(string: )` – + Specifies the role name to use for this operation. This is specified as part + of the URL. + +- `value` `(string: )` – + Specifies the plaintext of an issued token or tokens to delete. + +- `expiration` `(string: "")` - The precise expiration of the token. If omitted, + this specifically deletes tokens with no expiration. If the string + "any", will delete tokens with any or no expiration. Otherwise, + the string must be the RFC3339 formatted time and date of expiration. `expiration` + may not be used at the same time as `min_expiration` and `max_expiration`. + +- `min_expiration` `(string: "")` - The minimum expiration time of the token, + inclusive, as an RFC3339 formatted time and date. + `min_expiration` may not be used at the same time as `expiration`. + When provided, `max_expiration` must also be provided. + +- `max_expiration` `(string: "")` - The maximum expiration time of the token, + inclusive, as an RFC3339 formatted time and date. + `max_expiration` may not be used at the same time as `expiration`. + When provided, `min_expiration` must also be provided. + +- `transformation` `(string)` – + Specifies the transformation within the role that should be used for this + decode operation. If a single transformation exists for role, this parameter + may be skipped and will be inferred. If multiple transformations exist, one + must be specified. + +- `reference` `(string: "")` - + A user-supplied string that will be present in the `reference` field on the + corresponding `batch_results` item in the response, to assist in understanding + which result corresponds to a particular input. Only valid on batch requests + when using ‘batch_input’ below. + +- `batch_input` `(array: nil)` - + Specifies a list of items to be decoded in a single batch. When this + parameter is set, the 'value', 'transformation', and 'reference' parameters are + ignored. Instead, the aforementioned parameters should be provided within + each object in the list. In addition, batched requests can add the 'reference' + field described above. + + ```json + [ + { + "value": "1111-1111-1111-1111", + "expiration": "any", + "transformation": "ccn-tokenization" + } + ] + ``` + +### Sample payload + +```json +{ + "value": "1111-1111-1111-1111", + "min_expiration": "2022-06-06T3:14:15+00:00", + "min_expiration": "2022-06-07T9:26:53+00:00", + "transformation": "ccn-tokenization" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + --data @payload.json \ + http://127.0.0.1:8200/v1/transform/tokenized/example-role +``` + + ## Retrieve token metadata This endpoint retrieves metadata for a tokenized value using a named role.