Document tokenization DELETE (#26622)

* Document tokenization DELETE * typo * Update website/content/api-docs/secret/transform.mdx Co-authored-by: Steven Clark <[email protected]> --------- Co-authored-by: Steven Clark <[email protected]>
hashicorp · May 1, 2024 · c4839ad · c4839ad
1 parent 2593136
commit c4839ad
Showing 1 changed file with 157 additions and 1 deletion.
diff --git 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: <required>)` –
-  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: <required>)` –
+  Specifies the role name to use for this operation. This is specified as part
+  of the URL.
+
+- `token` `(string: <required>)` –
+  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<object>: 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: <required>)` –
+  Specifies the role name to use for this operation. This is specified as part
+  of the URL.
+
+- `value` `(string: <required>)` –
+  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<object>: 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.