I Tried Resetting TOTP Settings by Directly Calling Amazon Cognito's AdminDeleteSoftwareToken
This page has been translated by machine translation. View original
Introduction
On August 26, 2026, Amazon Cognito added AdminDeleteSoftwareToken, which allows administrators to delete a user's software token for TOTP. It is an API for deleting the token of a user who has lost their TOTP device so that MFA can be set up again.
| Item | Before AdminDeleteSoftwareToken was added | After it was added |
|---|---|---|
| Administrator resetting TOTP for a target user | There is no dedicated administrator API to delete an existing TOTP token | Can be deleted with AdminDeleteSoftwareToken |
| Recovery while keeping MFA required | You had to consider changing the MFA settings of the entire user pool, or deleting and recreating the user | Delete the target user's token, then start the setup flow again from MFA_SETUP, which is returned at the next authentication |
| Scope of impact | The entire user pool, or the target user's ID and related data | The target user's software token |
Preparation
I performed the verification in ap-northeast-1. After creating a user pool, I enabled software token MFA and made MFA required, then prepared an app client for password authentication and a dummy user. Because I will not publish actual IDs or passwords, variables are used below.
User pool with required MFA
First, I created a user pool for password authentication.
USER_POOL_ID=$(aws cognito-idp create-user-pool \
--pool-name totp-reset-test-pool \
--policies '{"PasswordPolicy":{"MinimumLength":8,"RequireUppercase":true,"RequireLowercase":true,"RequireNumbers":true,"RequireSymbols":false}}' \
--query 'UserPool.Id' --output text)
I enabled software token MFA and made MFA required for the pool.
aws cognito-idp set-user-pool-mfa-config \
--user-pool-id "$USER_POOL_ID" \
--mfa-configuration ON \
--software-token-mfa-configuration Enabled=true
App client and dummy user
I created an app client that performs password authentication.
CLIENT_ID=$(aws cognito-idp create-user-pool-client \
--user-pool-id "$USER_POOL_ID" \
--client-name totp-test-client \
--no-generate-secret \
--explicit-auth-flows \
ALLOW_ADMIN_USER_PASSWORD_AUTH \
ALLOW_REFRESH_TOKEN_AUTH \
ALLOW_USER_PASSWORD_AUTH \
--query 'UserPoolClient.ClientId' --output text)
I created a dummy user that sends no notifications and set a permanent password.
USERNAME=testuser
PASSWORD='<TestUserPassword>'
aws cognito-idp admin-create-user \
--user-pool-id "$USER_POOL_ID" \
--username "$USERNAME" \
--temporary-password "$PASSWORD" \
--message-action SUPPRESS
aws cognito-idp admin-set-user-password \
--user-pool-id "$USER_POOL_ID" \
--username "$USERNAME" \
--password "$PASSWORD" \
--permanent
After the password was set, the dummy user became CONFIRMED. When I authenticated, an MFA_SETUP challenge was returned.
TOTP registration
For the dummy user with the permanent password set, I obtained an MFA_SETUP session and registered TOTP.
MFA_SETUP_SESSION="$(aws cognito-idp admin-initiate-auth \
--user-pool-id "$USER_POOL_ID" \
--client-id "$CLIENT_ID" \
--auth-flow ADMIN_USER_PASSWORD_AUTH \
--auth-parameters "USERNAME=$USERNAME,PASSWORD=$PASSWORD" \
--query Session --output text)"
ASSOCIATE_JSON="$(aws cognito-idp associate-software-token \
--session "$MFA_SETUP_SESSION" \
--output json)"
TOTP_SECRET="$(printf '%s' "$ASSOCIATE_JSON" | \
python3 -c 'import json,sys; print(json.load(sys.stdin)["SecretCode"])')"
ASSOCIATE_SESSION="$(printf '%s' "$ASSOCIATE_JSON" | \
python3 -c 'import json,sys; print(json.load(sys.stdin)["Session"])')"
So that I would not need to install oathtool locally, I generated the code with oathtool inside a Docker container. TOTP_SECRET and the generated code are not printed to standard output.
TOTP_CODE="$(docker run --rm -e "TOTP_SECRET=$TOTP_SECRET" alpine sh -c \
'apk add --no-cache oath-toolkit-oathtool >/dev/null && \
oathtool --totp --base32 "$TOTP_SECRET"')"
aws cognito-idp verify-software-token \
--session "$ASSOCIATE_SESSION" \
--user-code "$TOTP_CODE" \
--query Status --output text
After SUCCESS was returned, I confirmed that a SOFTWARE_TOKEN_MFA challenge was returned during authentication.
API verification
For the user whose TOTP was registered in the preparation, I checked the same items before and after deletion.
Check before deletion
Authentication factors
aws cognito-idp admin-get-user-auth-factors \
--user-pool-id "$USER_POOL_ID" \
--username "$USERNAME" \
--query ConfiguredUserAuthFactors --output json
[
"PASSWORD",
"SOFTWARE_TOKEN"
]
Challenge during authentication
aws cognito-idp admin-initiate-auth \
--user-pool-id "$USER_POOL_ID" \
--client-id "$CLIENT_ID" \
--auth-flow ADMIN_USER_PASSWORD_AUTH \
--auth-parameters "USERNAME=$USERNAME,PASSWORD=$PASSWORD" \
--query ChallengeName --output text
SOFTWARE_TOKEN_MFA
The password and software token are set as authentication factors, and a TOTP challenge is returned during authentication.
API execution
As of this writing, the latest AWS CLI 2.36.32 and boto3 1.43.81 did not support AdminDeleteSoftwareToken.
Instead of the AWS CLI and boto3, I called it directly with a SigV4 signature added using botocore.
import json
from urllib.request import Request, urlopen
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
from botocore.session import get_session
region = 'ap-northeast-1'
payload = {
'UserPoolId': 'ap-northeast-1_XXXXXXXXX',
'Username': 'testuser',
}
request = AWSRequest(
method='POST',
url=f'https://cognito-idp.{region}.amazonaws.com/',
data=json.dumps(payload, separators=(',', ':')).encode(),
headers={
'Content-Type': 'application/x-amz-json-1.0',
'X-Amz-Target': 'AWSCognitoIdentityProviderService.AdminDeleteSoftwareToken',
},
)
credentials = get_session().get_credentials().get_frozen_credentials()
SigV4Auth(credentials, 'cognito-idp', region).add_auth(request)
prepared = request.prepare()
with urlopen(
Request(prepared.url, data=prepared.body, headers=dict(prepared.headers.items()), method='POST')
) as response:
print(f'HTTP {response.status}')
print(response.read().decode() or '{}')
Check after deletion
After running AdminDeleteSoftwareToken, I checked the authentication factors and the challenge during password authentication using the same commands as before deletion.
Authentication factors
[
"PASSWORD"
]
The software token was deleted, and the only authentication factor became the password.
Challenge during authentication
MFA_SETUP
At the next authentication, an MFA_SETUP challenge was returned, allowing a new software token to be set up.
Summary
For users who have no alternative factor such as SMS MFA and use only TOTP as their MFA factor, recovery after losing a device was a challenge. With AdminDeleteSoftwareToken, you can implement a recovery flow that resets only the target user's TOTP, returns them to MFA_SETUP at the next authentication, and prompts them to register again.
If you had put off making MFA required in Cognito because of recovery when a TOTP device is lost, please try this flow.
Going forward, I hope official SDK support will arrive, and that APIs will be provided that let administrators reset authentication factors other than TOTP, including passkeys, on a per-user basis.
