---
layout: api
page_title: /identity/mfa/method/totp - HTTP API
description: >-
  The '/identity/mfa/method/totp' endpoint focuses on managing TOTP MFA behaviors in Vault.
---

## 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. Supported from Vault 1.13.0.

- `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

```json
{
  "issuer": "vault"
}
```

### Sample Request

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

```shell-session
$ 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

```shell-session
$ 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

```json
{
  "data": {
    "algorithm": "SHA1",
    "digits": 6,
    "id": "4c6b1968-b385-4c46-ac5e-9b74e7b206be",
    "issuer": "vault",
    "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](/vault/api-docs/secret/identity/mfa/login-enforcement).

| Method   | Path                            |
| :------- | :------------------------------ |
| `DELETE` | `/identity/mfa/method/totp/:id` |

### Parameters

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

### Sample Request

```shell-session
$ 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 in the current namespace or in parent namespaces.

| Method | Path                        |
| :----- | :-------------------------- |
| `LIST` | `/identity/mfa/method/totp` |

### Sample Request

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

### Sample Response

```json
{
  "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

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

### Sample Request

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

### Sample Response

```json
{
  "data": {
    "barcode": "  DQcxAEDOOz+2troUZaq1hNP40lr/eP61TicbP5nO6joWYgSBmIIgZx7ysiNu+ruj6dB5q7D4ii5Oo82EP+UYgiBkIYob0/pCV2/Uda7/TunX1PJHNq9qvGvN/HgcLMQNBzEAQM1p5WdM6kI mv5zReNo9uvtet+WTz+sBC/EAQMxDEjO0zF99dA9it+6jOM7qe+dKqde7V/qP5nP5eWIgZCGIGgpix3UNUbsXkq/Xd2Thd35zqE5v66Hb9YCFmIIgZCGLGlT3kwS1fUbcGsVq3HvUXnY/U+ ExEZW/DQsxAEDMQxIzS+0Mybq3REd1c3ur5qBs7z/a4zjNWsBAzEMQMBDHjZQ+Z+oAeqGv42o9aq5j1m5HN51ZdfWX+WIgZCGIGgpixfX8I/DmwEDP+DQAA//9kwGH4xZewMgAAAABJRU5E rkJggg==",
    "url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&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

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

### Sample Request

```shell-session
$ 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

```json
{
  "data": {
    "barcode": " ",
    "url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&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

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

### Sample Request

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