TeamCity REST API Reference
 
2023.05
You are viewing the documentation for an earlier version of TeamCity REST API Reference.
  1. Common Use Cases
  2. Manage Server
  3. Manage Two-Factor Authentication

Manage Two-Factor Authentication

Last modified: 12 October 2023

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.

tip

The User object has the respective boolean field enabled2FA.

Setup 2FA

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

POST
/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:

POST
/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:

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

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

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

Generate recovery keys

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

POST
/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

To refresh grace period (a period when user can sign in without enabled 2FA) for a specific user, use the following endpoint:

POST
/app/rest/2FA/<userLocator>/refreshGracePeriod

Grace period length is managed by the teamcity.auth.2fa.grace.period property; the default value is 1 week.