totp

Configure TOTP MFA method

This endpoint defines an MFA method of type TOTP.

Method	Path
POST	/identity/mfa/method/totp/:method_id

Parameters

• method_id (string: "") - Optional UUID to specify if updating an existing method.

• method_name (string) - The unique name identifier for this MFA method.

• issuer (string: <required>) - The name of the key's issuing organization.

• period (int or duration format string: 30) - The length of time used to generate a counter for the TOTP token calculation.

• key_size (int: 20) – Specifies the size in bytes of the generated key.

• qr_size (int: 200) - The pixel size of the generated square QR code.

• algorithm (string: "SHA1") – Specifies the hashing algorithm used to generate the TOTP code. Options include "SHA1", "SHA256" and "SHA512".

• digits (int: 6) - The number of digits in the generated TOTP token. This value can either be 6 or 8.

• skew (int: 1) - The number of delay periods that are allowed when validating a TOTP token. This value can either be 0 or 1.

• max_validation_attempts (int: 5) - The maximum number of consecutive failed validation attempts.

Sample payload

{
  "issuer": "openbao"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/mfa/method/totp

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/mfa/method/totp/1f36d4cf-52c9-475d-a5cd-49c573c54e55

Read TOTP MFA method

This endpoint queries the MFA configuration of TOTP type for a given method ID.

Method	Path
GET	/identity/mfa/method/totp/:id

Parameters

• id (string: <required>) – UUID of the MFA method.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be

Sample response

{
  "data": {
    "algorithm": "SHA1",
    "digits": 6,
    "id": "4c6b1968-b385-4c46-ac5e-9b74e7b206be",
    "issuer": "openbao",
    "key_size": 20,
    "period": 30,
    "qr_size": 200,
    "skew": 1,
    "type": "totp",
    "namespace": ""
  }
}

Delete TOTP MFA method

This endpoint deletes a TOTP MFA method. MFA methods can only be deleted if they're not currently in use by a login enforcement.

Method	Path
DELETE	/identity/mfa/method/totp/:id

Parameters

• id (string: <required>) - UUID of the MFA method.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be

List TOTP MFA methods

This endpoint lists TOTP MFA methods that are visible.

Method	Path
LIST	/identity/mfa/method/totp

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/mfa/method/totp

Sample response

{
  "data": {
    "keys": [
      "1f36d4cf-52c9-475d-a5cd-49c573c54e55",
      "4c6b1968-b385-4c46-ac5e-9b74e7b206be"
    ]
  }
}

Generate a TOTP MFA secret

This endpoint generates an MFA secret in the entity of the calling token, if it doesn't exist already, using the configuration stored under the given MFA method ID.

Method	Path
POST	/identity/mfa/method/totp/generate

Parameters

• method_id (string: <required>) - UUID of the MFA method.

Sample payload

{
  "method_id": "1f36d4cf-52c9-475d-a5cd-49c573c54e55"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/mfa/method/totp/generate

Sample response

{
  "data": {
    "barcode": "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 rkJggg==",
    "url": "otpauth://totp/openbao:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=openbao&period=30&secret=XVE7TOZWJVEWQOATOD7 U53IEAJG72Z2I"
  }
}

Administratively generate a TOTP MFA secret

This endpoint can be used to generate a TOTP MFA secret. Unlike the generate API which stores the generated secret on the entity ID of the calling token, the admin-generate API stores the generated secret on the given entity ID.

Method	Path
POST	/identity/mfa/method/totp/admin-generate

Parameters

• method_id (string: <required>) - UUID of the MFA method.

• entity_id (string: <required>) - Entity ID on which the generated secret needs to get stored.

Sample payload

{
  "method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4",
  "entity_id": "9189f7fd-e3f5-436b-a835-cb14864b1e01"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json
    http://127.0.0.1:8200/v1/identity/mfa/method/totp/admin-generate

Sample response

{
  "data": {
    "barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGZElEQVR4nOyd7W4jNwxFkyLv/8pbpMAAHnUo8pJyc1Oc82OB2KOP9QVFSyTlrz9/PsCIv356AnDn6/ufz89e48i6ov6u59f319ezfqtWnf2/snHX19XnVL7bYyFmIIgZCGLG5/e61V2b37WWXkRr9+lxonEvqv1XfeHK6/NYiBkIYgaCmPH19GK2j4ieX9/P9h0R2T6l+pzqYzKfmM0zQvk8sRAzEMQMBDHj0YdMqa6Z1TOvyDdF/VTPnqLnVzIfePLEHAsxA0HMQBAz3uJDqvuVbO1Vv/934yzReNV4ykmwEDMQxAwEMePRh5xeG6fxjNXnVM+Y1HHVM7Tq56R8nliIGQhiBoKYcfMhp2LT6hp7UY2hV8dTY/KZT1N9SufzxELMQBAzEMSMf3zI6X2HembUXbuz8dT9g+qLIiafJxZiBoKYgSBm3OpDunlMartTubrdeEUWI1dzAqa5wK9gIWYgiBkIYsaReIi6P1jbqd/7qznDqm9SfcKJs6sVLMQMBDEDQcz43K3z3fqLaf336fiFymQf8dRe8aVYiBkIYgaCmHHzIdW8pGo8QT1rOuULTvkc9a6TqD+lTgULMQNBzEAQMx7jIRdqjV7ULvpbrReJxl/nodYodseLxu/GWz6wED8QxAwEMeN2X9ZK9/4neRLDNfrUc919yPp8t/8PLMQPBDEDQcyQ6tTVO0JWqvGT6PWu75jub6L+T/kg4iHGIIgZCGLGKB5yKn5SpVuDWKXrI0/4jgssxAwEMQNBzNieZWV0v/erZ0Knxp3OYxoXqoyPhZiBIGYgiBmPub1q7m7G6fiB2n+3niSbZwT7kP8RCGIGgpjxeF9W5iPU8/+ofUY1r6q6ZkfzmtbJV2skozw04iHGIIgZCGKGlJeVvZ61V+MX07OiqJ9oftE41fGm9TD4EEMQxAwEMaN010lW1zGNoVfX+OrZl/rcfx0P2c0XCzEDQcxAEDMe87K68YBubH7tdxonmcb0q+2qZ2DK/gkLMQNBzEAQM2516lXUs6GIbA3v+qruPinrX/Ud0Xx288JCzEAQMxDEjG2NYXf/odztsXuuEoOu9BO93933RONm86n0h4WYgSBmIIgZt9+gqtaDq7m3K2rObnc+UT/Z36f2MZ28MCzEDAQxA0HMaJ1lTevBo/5OxRsysv1O9Fx1nO4Z3QcW4geCmIEgZki/H1Klu+Z369PVeVXHexfEQ34RCGIGgpjxWGN40c1VXdtXaxW79SLTOvqonVpDqdavkNv7C0AQMxDEjNK9vdP4gFq3ntV1Z+NEf099ZEZ1vrv+sBAzEMQMBDFjW2PYjT9U4xqqT1D7/ak4j5rn9QoWYgaCmIEgZpTu7e2u5Vk/4aQO3XFSHUc9s1rnNfVdr/1hIWYgiBkIYsZtH6LGA9Z20d8Z3fuq1HyqUznC1fZVX0c8xBgEMQNBzNje2xvxrlzYan1K1H82fjXOUfU12XzW5yufBxZiBoKYgSBmSL+FezE9s1lR9yHq2VvUT7fefOpjd58fFmIGgpiBIGZId52sr6u5u9M7RtTn1Hmr8ZzqnSvK2R4WYgaCmIEgZmzjIdHr3Rzfi278I3pdvStFrWVUfU52d8quPRZiBoKYgSBmbOvU//Xwobr1U7FpNV8qatetm4+onvU9jYuFmIEgZiCIGbf7srLv1d01vLsWqzmzapymeyaWfQ5qXtsrWIgZCGIGgphR+g2q9f0V9Y6SartsXtP8qOmZWDTe5AwMCzEDQcxAEDMeY+rVfUj0fLddN9Y+3feodfPd+pnKvLAQMxDEDAQxY1unPo11q+2i8adxCXV+an/qfHbzwELMQBAzEMQMKaYediL6FDVmruaBTWsU1bMwdT67/zcWYgaCmIEgZrR+g+piPata18Tu9/Zurq5aTxLNV833qs6nMg8sxAwEMQNBzHisD8lQ6y3W/qt3kpyuS8/ez3xiNL/qfMjL+oUgiBkIYkYppn7R9THd56s5tBGn60myfcSJ3GMsxAwEMQNBzGjdlxXRja1068mj9tla3c3DysaLxon+fgILMQNBzEAQM476kG5c5aJ7BnS6bqX6+jS/jLysXwCCmIEgZmx/x7DK6btCurF31WdMawPfkXOMhZiBIGYgiBmPvx+iUo2RV/vp3llSpZuXpfqgbNwnsBAzEMQMBDHjSH0InAMLMePvAAAA//8x2VnbmmL6HQAAAABJRU5ErkJggg==",
    "url": "otpauth://totp/openbao:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=openbao&period=30&secret=6HQ4RZ7GM6MMLRKVDCI23LXNZF7UDZ2U"
  }
}

Administratively destroy TOTP MFA secret

This endpoint deletes a TOTP MFA secret from the given entity ID.

To overwrite a secret on the entity, explicitly deleting the secret first is required. This API can be used to delete the secret and the generate or admin-generate APIs should be used to regenerate a new secret.

Method	Path
POST	/identity/mfa/method/totp/admin-destroy

Parameters

• method_id (string: <required>) - UUID of the MFA method.

• entity_id (string: <required>) - Entity ID from which the MFA secret should be removed.

Sample payload

{
  "method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4",
  "entity_id": "9189f7fd-e3f5-436b-a835-cb14864b1e01"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/mfa/method/totp/admin-destroy