TeamCity REST API Reference 2024.07 Help

Manage Two-Factor Authentication

In this article, we explore common use cases concerning two-factor authentication feature control via TeamCity REST API. Note that these endpoints accept only authentication via access tokens.

Setup 2FA

To start setup of 2FA for the current user, use the following endpoint:

/app/rest/2FA/setup

The method will return a secret key, set of recovery keys and UUID for the confirmation of setup.

Confirm 2FA setup

To confirm the setup of 2FA for the current user, use the following endpoint:

/app/rest/2FA/confirm?uuid=<uuid>&password=<password>

where uuid is the UUID returned by /setup method, and password is 6-digit TOTP password. If supplied password matches the secret key found by UUID, 2FA setup is finished.

Disable 2FA for a user

To remove secret key and recovery keys for a specific user, use:

/app/rest/2FA/<userLocator>/disable

Here, userLocator is typed as UserLocator. For example, to disable 2FA for john.doe username, send:

/app/rest/2FA/username:john.doe/disable

To prevent users from being unable to access TeamCity, disabling 2FA also triggers the default one-week grace period refresh.

Generate recovery keys

To generate a new set of recovery keys for the current user, use:

/app/rest/2FA/newRecoveryKeys

The format of recovery keys is [0-9a-f]{6}-[0-9a-f]{6}. Old recovery keys will be discarded.

Refresh grace period for a user

The grace period allows users without configured 2FA to continue using TeamCity. This period duration depends on the teamcity.auth.2fa.grace.period property; the default value is one week.

This period is automatically refreshed when you explicitly disable 2FA for users. To manually refresh a grace period for a specific user, use the following endpoint:

/app/rest/2FA/<userLocator>/refreshGracePeriod
Last modified: 30 September 2024