# Replace a Keycloak one-time code

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/replace-a-keycloak-one-time-code/)

Replace a test authenticator in Keycloak. Check which sessions remain after you remove it, then verify that Keycloak rejects the old code and accepts the replacement.

## Before you start

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

- Use a disposable realm, one non-admin test user with a working code and a separate administrator with credentials and session permissions. Keep the original KeySigner entry until you check the replacement.

## Data and access

- **Shared or checked**. Keycloak removes the old enrollment and verifies codes from the replacement. Realm session controls can end existing Keycloak sessions.
- **Check separately**. Check sessions at affected client apps as well. Removing a factor alone does not end each session.

## 1. Confirm the test account and recovery access

Open the Keycloak Admin Console in a separate administrator session. Check the realm, exact username and user label of the authenticator you plan to replace. In a private browser window, confirm the current code still works for the test user.

**Check.** The old code opens the intended test account, and the separate administrator can manage that user’s credentials.

## 2. Require enrollment and remove the old authenticator

Open Users and choose the test user. Under Details, add Configure OTP to Required user actions and save. Open Credentials, find the old authenticator by its label and choose Delete from its actions menu.

**Check.** Configure OTP is saved for the test user. The named OTP credential disappears from Credentials, and the user’s other methods remain listed.

## 3. End the test user’s active sessions

In the same user’s Sessions tab, check for sessions that remain after deleting the credential. Choose Logout all sessions, then Confirm. Reload the old Account Console tab. Check connected apps separately if your test includes any.

**Check.** The Sessions tab shows no active sessions for the test user. Reloading the previous Account Console leads back to the sign-in page.

## 4. Enroll a replacement and try both codes

Close the private window used for the earlier test. In a fresh private window, sign in to the same realm and account. In KeySigner, add the new setup QR as a separate account entry and give the new Keycloak authenticator a distinct label. Keep both QR codes private. After enrollment, close all private windows for the test user and open a new one. Wait for a fresh code and try the old entry once, then enter a fresh code from the replacement entry. After both checks pass, you can remove the old KeySigner entry.

![A local Keycloak sign-in form with an empty one-time code field and an invalid authenticator code message.](https://keysigner.io/integrations/guides/replace-a-keycloak-one-time-code/keycloak-old-code-rejected.png)

The fresh sign-in rejected a current code from the original Keycloak setup.

**Check.** Keycloak shows a new setup QR at enrollment. The fresh sign-in rejects the old code and accepts the replacement code. Credentials shows the replacement label.

## Check your result

Removing an authenticator in Keycloak and ending sessions are separate actions. Removing a KeySigner entry from a device leaves the provider’s enrollment in place. If a device is lost or a setup key may have been exposed, have the separate administrator remove the old credential and end affected sessions promptly. Verify access separately in each affected app.

### What we tested

**Tested on November 18, 2026.** In a local Keycloak 26.8.2 realm, we used the KeySigner vault and Chromium with a disposable user. Removing the original credential left two sessions active. Logging out those sessions sent the old browser back to sign-in. Keycloak accepted the replacement and rejected a fresh code from the original setup.

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

## If you get stuck

### Keycloak opens the account without showing an enrollment prompt

Stop and check the exact realm, user and test browser. Confirm Configure OTP is assigned to the user and try again from a private window. A conditional OTP flow can skip the code step when the user has no OTP credential. Keep the administrator session available until a fresh sign-in shows the new setup QR and accepts a replacement code.

## Tools in this guide

- [Keycloak](https://keysigner.io/integrations/keycloak/)
  - [Review realm and administrator settings](https://www.keycloak.org/docs/latest/server_admin/)
  - [Set up or reset a one-time code](https://www.keycloak.org/docs/latest/server_admin/#proc_creating-otp_server_administration_guide)
  - [Setup requirements](https://keysigner.io/integrations/setup-requirements/#keycloak)

## Setup instructions

- [Set up a Keycloak one-time code](https://keysigner.io/integrations/guides/set-up-a-keycloak-one-time-code/)
- [Manage a Keycloak user’s credentials](https://www.keycloak.org/docs/latest/server_admin/#ref-user-credentials_server_administration_guide)
- [Set a required action for a Keycloak user](https://www.keycloak.org/docs/latest/server_admin/#proc-setting-required-actions_server_administration_guide)
- [Manage Keycloak sessions](https://www.keycloak.org/docs/latest/server_admin/#managing-user-sessions)
- [Use the integration rollout checklist](https://keysigner.io/integrations/rollout-checklist/)

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