---
layout: "docs"
page_title: "TOTP Secret Backend"
sidebar_current: "docs-secrets-totp"
description: |-
  The TOTP secret backend for Vault generates time-based one-time use passwords.
---

# TOTP Secret Backend

Name: `totp`

The TOTP secret backend for Vault will allow Vault users to store their multi-factor
authentication keys in Vault and use the API to retrieve time-based one-time use passwords
on demand. The backend can also be used to generate a new key and validate passwords generated by that key.

This page will show a quick start for this backend. For detailed documentation
on every path, use `vault path-help` after mounting the backend.

## Quick Start

The first step to using the TOTP backend is to mount it.
Unlike the `generic` backend, the `totp` backend is not mounted by default.

```text
$ vault mount totp
Successfully mounted 'totp' at 'totp'!
```

The next step is to configure a key. For example, lets create
a "test" key by passing in a TOTP key url:

```text
$ vault write totp/keys/test \
    url="otpauth://totp/Vault:test@gmail.com?secret=Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G&issuer=Vault"
Success! Data written to: totp/keys/test
```

By writing to the `keys/test` path we are defining the `test` key.

To generate a new set of credentials, we simply read from that key using the `code` path:

```text
$ vault read totp/code/test
Key           	Value
code            135031
```
Vault is now configured to create time-based one-time use passwords!

By reading from the `code/test` path, Vault has generated a new
time-based one-time use password using the `test` key configuration.

Using ACLs, it is possible to restrict using the TOTP backend such
that trusted operators can manage the key definitions, and both
users and applications are restricted in the credentials they are
allowed to read.

The TOTP backend can also be used to generate new keys and validate passwords generated using those keys.

In order to generate a new key, set the generate flag to true and pass in an issuer and account name.

```text
$ vault write totp/keys/test \
    generate=true issuer=Vault account_name=test@gmail.com
```
A base64 encoded barcode and url will be returned upon generating a new key. These can be given to client applications that
can generate passwords. You can validate those passwords by writing to the `code/test` path.

```text
$ vault write totp/code/test \
    code=127388
Key           	Value
valid           true
```

If you get stuck at any time, simply run `vault path-help totp` or with a
subpath for interactive help output.

## API

The TOTP secret backend has a full HTTP API. Please see the
[TOTP secret backend API](/api/secret/totp/index.html) for more
details.