mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-10-30 02:02:43 +00:00
f4f0412b6a
* Convert documentation titles to sentense case * Docker, Google, Foundry, Cloud proper case
270 lines
8.6 KiB
Plaintext
270 lines
8.6 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: TOTP - Secrets Engines - HTTP API
|
||
description: This is the API documentation for the Vault TOTP secrets engine.
|
||
---
|
||
|
||
# TOTP secrets engine (API)
|
||
|
||
This is the API documentation for the Vault TOTP secrets engine. For general
|
||
information about the usage and operation of the TOTP secrets engine, please see
|
||
the [TOTP documentation](/vault/docs/secrets/totp).
|
||
|
||
This documentation assumes the TOTP secrets engine is enabled at the `/totp`
|
||
path in Vault. Since it is possible to enable secrets engines at any location,
|
||
please update your API calls accordingly.
|
||
|
||
## Create key
|
||
|
||
This endpoint creates or updates a key definition.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------- |
|
||
| `POST` | `/totp/keys/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the key to create. This is specified as part of the URL.
|
||
|
||
- `generate` `(bool: false)` – Specifies if a key should be generated by Vault or if a key is being passed from another service.
|
||
|
||
- `exported` `(bool: true)` – Specifies if a QR code and url are returned upon generating a key. Only used if generate is true.
|
||
|
||
- `key_size` `(int: 20)` – Specifies the size in bytes of the Vault generated key. Only used if generate is true.
|
||
|
||
- `url` `(string: "")` – Specifies the TOTP key url string that can be used to configure a key. Only used if generate is false.
|
||
|
||
- `key` `(string: <required - if generate is false and url is empty>)` – Specifies the root key used to generate a TOTP code. Only used if generate is false.
|
||
|
||
- `issuer` `(string: "" <required - if generate is true>)` – Specifies the name of the key’s issuing organization.
|
||
|
||
- `account_name` `(string: "" <required - if generate is true>)` – Specifies the name of the account associated with the key.
|
||
|
||
- `period` `(int or duration format string: 30)` – Specifies the length of time in seconds used to generate a counter for the TOTP code calculation.
|
||
|
||
- `algorithm` `(string: "SHA1")` – Specifies the hashing algorithm used to generate the TOTP code. Options include "SHA1", "SHA256" and "SHA512".
|
||
|
||
- `digits` `(int: 6)` – Specifies the number of digits in the generated TOTP code. This value can be set to 6 or 8.
|
||
|
||
- `skew` `(int: 1)` – Specifies the number of delay periods that are allowed when validating a TOTP code. This value can be either 0 or 1. Only used if generate is true.
|
||
|
||
- `qr_size` `(int: 200)` – Specifies the pixel size of the square QR code when generating a new key. Only used if generate is true and exported is true. If this value is 0, a QR code will not be returned.
|
||
|
||
### Sample payload
|
||
|
||
```json
|
||
{
|
||
"url": "otpauth://totp/Google:test@gmail.com?secret=Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G&issuer=Google"
|
||
}
|
||
```
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/totp/keys/my-key
|
||
```
|
||
|
||
### Sample payload
|
||
|
||
```json
|
||
{
|
||
"generate": true,
|
||
"issuer": "Google",
|
||
"account_name": "test@gmail.com"
|
||
}
|
||
```
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/totp/keys/my-key
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"barcode": "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",
|
||
"url": "otpauth://totp/Google:test@gmail.com?algorithm=SHA1&digits=6&issuer=Google&period=30&secret=HTXT7KJFVNAJUPYWQRWMNVQE5AF5YZI2"
|
||
}
|
||
}
|
||
```
|
||
|
||
If a QR code is returned, it consists of base64-formatted PNG bytes. You can embed it in a web page by including the base64 string in an `img` tag with the prefix `data:image/png;base64`
|
||
|
||
```
|
||
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUh.." />
|
||
```
|
||
|
||
## Read key
|
||
|
||
This endpoint queries the key definition.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------- |
|
||
| `GET` | `/totp/keys/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the key to read. This is specified as part of the URL.
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/totp/keys/my-key
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"account_name": "test@gmail.com",
|
||
"algorithm": "SHA1",
|
||
"digits": 6,
|
||
"issuer": "Google",
|
||
"period": 30
|
||
}
|
||
}
|
||
```
|
||
|
||
## List keys
|
||
|
||
This endpoint returns a list of available keys. Only the key names are
|
||
returned, not any values.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------- |
|
||
| `LIST` | `/totp/keys` |
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
http://127.0.0.1:8200/v1/totp/keys
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"auth": null,
|
||
"data": {
|
||
"keys": ["my-key"]
|
||
},
|
||
"lease_duration": 0,
|
||
"lease_id": "",
|
||
"renewable": false
|
||
}
|
||
```
|
||
|
||
## Delete key
|
||
|
||
This endpoint deletes the key definition.
|
||
|
||
| Method | Path |
|
||
| :------- | :----------------- |
|
||
| `DELETE` | `/totp/keys/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the key to delete. This
|
||
is specified as part of the URL.
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
http://127.0.0.1:8200/v1/totp/keys/my-key
|
||
```
|
||
|
||
## Generate code
|
||
|
||
This endpoint generates a new time-based one-time use password based on the named
|
||
key.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------- |
|
||
| `GET` | `/totp/code/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the key to create
|
||
credentials against. This is specified as part of the URL.
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/totp/code/my-key
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"code": "810920"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Validate code
|
||
|
||
This endpoint validates a time-based one-time use password generated from the named
|
||
key.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------- |
|
||
| `POST` | `/totp/code/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the key used to generate the password. This is specified as part of the URL.
|
||
|
||
- `code` `(string: <required>)` – Specifies the password you want to validate.
|
||
|
||
### Sample payload
|
||
|
||
```json
|
||
{
|
||
"code": "123802"
|
||
}
|
||
```
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/totp/code/my-key
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"valid": true
|
||
}
|
||
}
|
||
```
|