# Test a HashiCorp Vault sign-in code with KeySigner

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/test-a-vault-sign-in-code/)

Protect a test user’s password sign-in with a code from KeySigner. Check that Vault requires the code, issues a token for the right user, and restores the prior sign-in when the pilot rule is removed.

## Before you start

**KeySigner on iPhone or Mac with Sign-in codes**

- Use a disposable Vault instance with a username and password test user, a separate recovery administrator, and access to run Vault API calls.

## Data and access

- **Shared or checked**. Vault checks the password and code for the test identity before issuing a Vault token. Deleting the pilot requirement changes the next sign-in.
- **Check separately**. The token’s policies govern secret access. Existing tokens can require a separate revocation.

## Who does what

- **Vault administrator**. Set up Login MFA for one test identity and keep a separate administrator session available to remove the test rule.
- **Test user**. Save the QR code in KeySigner and check what Vault returns from a fresh session.

## 1. Prepare a separate Vault test user

Use a disposable Vault instance with the username and password sign-in method enabled. Sign in as the pilot user once to establish a Vault identity and note its entity ID. Keep a separate administrator session available. Revoke the token from the initial pilot sign-in before testing the new rule.

**Check.** You have the pilot entity ID and can still reach the separate administrator.

## 2. Generate the setup QR code and save it in KeySigner

As the Vault administrator, create a time-based one-time password (TOTP) method with generation enabled. Use Vault’s admin-generate endpoint with that method ID and the pilot’s entity ID. Open the returned barcode as a private PNG. In KeySigner, open Accounts → Add (+) → Sign-in codes and backup, unlock Sign-in codes, and choose Add account. Scan the QR code or choose the PNG. Verify the issuer and account before you save, then remove the temporary image.

![KeySigner for Mac offers options to scan a QR code, choose an image, or enter a setup link.](https://keysigner.io/integrations/guides/set-up-a-time-based-sign-in-code/keysigner-add-account.png)

Use Add account to scan the Vault QR code or choose its PNG.

**Check.** KeySigner shows the expected Vault issuer and pilot account.

## 3. Require the code for the pilot identity

Create a named Login MFA enforcement rule that lists the TOTP method ID and only the pilot’s entity ID. Start a fresh client session and sign in with the pilot’s password. Inspect the response for an MFA requirement without a client token. Leave the independent administrator session open.

**Check.** The password returns an MFA challenge and no token.

## 4. Use a current code to check token issuance

For a single-request sign-in, supply the password and X-Vault-MFA header. Use your method ID followed by :passcode= and the current code from Show code in KeySigner. In the test instance, submit one incorrect code first and confirm Vault denies the request. Submit a fresh KeySigner code and use Vault’s token lookup to confirm that the new token belongs to the pilot identity.

**Check.** Vault rejects the incorrect code and returns a new token for the pilot when a current code is supplied.

## 5. Remove the pilot rule and check recovery

From the separate administrator session, remove the named test enforcement, then sign in again as the pilot to check the prior behavior. Revoke the tokens from the rehearsal and remove the unused test enrollment or discard the test instance.

**Check.** The pilot can sign in according to the prior rule after the test enforcement is removed.

## Check your result

Record the instance, sign-in method, pilot identity, and recovery administrator. Login MFA gates token issuance for the matching sign-in. Vault policies decide what that token can access. Previously issued tokens and workload identities have their own access and revocation controls.

### What we tested

**Tested on November 18, 2026.** In a disposable Vault Community 2.2.2 instance, the KeySigner vault imported Vault’s QR code. The password alone returned a challenge without a token. Vault denied an incorrect code and issued a token for the pilot identity with a current KeySigner code. Removing the test rule restored the prior password sign-in.

[How to verify your setup](https://keysigner.io/integrations/verify-a-setup/)

## If you get stuck

### Vault skips the challenge or denies the code

Check the test instance, sign-in mount, and entity ID if Vault skips the challenge. If a code is denied, match the MFA method ID and KeySigner entry to that same user. Check the clock on the device and Vault server and wait for a fresh code before retrying. Use the separate administrator to review or remove the pilot rule if the problem persists.

## Tools in this guide

- [HashiCorp Vault](https://keysigner.io/integrations/hashicorp-vault/)
  - [Define what a Vault policy can access](https://developer.hashicorp.com/vault/docs/concepts/policies)
  - [Setup requirements](https://keysigner.io/integrations/setup-requirements/#hashicorp-vault)

## Setup instructions

- [Configure Vault Login MFA](https://developer.hashicorp.com/vault/docs/auth/login-mfa)
- [Generate a TOTP method and enrollment barcode](https://developer.hashicorp.com/vault/api-docs/secret/identity/mfa/totp)
- [Scope a Vault Login MFA enforcement rule](https://developer.hashicorp.com/vault/api-docs/secret/identity/mfa/login-enforcement)
- [Replace a Vault sign-in code and check old tokens](https://keysigner.io/integrations/guides/replace-a-vault-sign-in-code/)
- [Inspect or revoke a Vault token](https://developer.hashicorp.com/vault/api-docs/auth/token)
- [Set up a time-based sign-in code in KeySigner](https://keysigner.io/integrations/guides/set-up-a-time-based-sign-in-code/)
- [Review a cloud resource access rule](https://keysigner.io/integrations/guides/check-cloud-resource-access/)
- [Test an authenticator code on a local Teleport cluster](https://keysigner.io/integrations/guides/test-a-teleport-sign-in-code/)

[More guides for this task](https://keysigner.io/integrations/tasks/set-up-sign-in-codes/)
