mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-10-29 09:42:25 +00:00
Document tokenization DELETE (#26622)
* Document tokenization DELETE * typo * Update website/content/api-docs/secret/transform.mdx Co-authored-by: Steven Clark <steven.clark@hashicorp.com> --------- Co-authored-by: Steven Clark <steven.clark@hashicorp.com>
This commit is contained in:
Scott Miller
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user