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.
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
Sample request
Sample payload
Sample request
Sample response
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
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
Sample response
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
Sample response
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
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
Sample response
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
Sample request
Sample response