# Turn on two-factor authentication

> Protect your account with an authenticator app, save your recovery codes, and turn two-factor authentication off again.

Source: https://docs.coritan.com/account/two-factor-authentication/

In the dashboard:

- /dashboard/settings/security: https://www.coritan.com/dashboard/settings/security

With two-factor authentication on, signing in takes your password and a six-digit code from an authenticator app on your phone. Someone who learns your password still cannot sign in without the phone. Coritan sends no codes by text message or email: the app makes them.

## Before you begin

- Sign in to the [dashboard](https://www.coritan.com/dashboard).
- Install an authenticator app that makes time-based codes, such as 1Password, Google Authenticator, Microsoft Authenticator, Authy or Aegis.
- Have somewhere safe to keep ten recovery codes, such as a password manager.

## Turn it on

1. In the sidebar, select **Settings**, then the **Security** tab.
2. In **Two-factor authentication**, select **Set up two-factor authentication**.
3. Scan the QR code with your authenticator app. The app adds `Coritan` and starts showing six digits that change every 30 seconds.

   If the app cannot scan, select **Cannot scan it? Enter the key manually** and type the key into the app, or select **Copy setup key**. The codes are time-based, six digits long, use SHA-1 and change every 30 seconds.

4. Type the six digits the app shows into **Confirm with the code from the app**, then select **Turn on two-factor**.
5. Save the ten recovery codes that appear: select **Copy codes** or **Download .txt**.
6. Tick **I have saved these codes somewhere safe.** and select **Done**.

> [!IMPORTANT]
> The recovery codes appear once. Each one signs you in one time if you lose your phone. Without the phone and without a code, only Coritan support can let you back in.

## Make new recovery codes

When you have used some recovery codes, or think someone has seen them, make a new set. The card shows **Low** when you have two or fewer left.

1. On the **Security** tab, select **New recovery codes…**.
2. Type the code your app shows. You can select **Use a recovery code instead** and type one of your remaining codes.
3. Select **Make new codes**.
4. Save the ten new codes, tick **I have saved these codes somewhere safe.** and select **Done**.

Your old codes stop working as soon as the new ones exist.

## Turn it off

1. On the **Security** tab, find **Danger zone** and select **Turn off two-factor…**.
2. Enter **Your password** and the code your app shows, or select **Use a recovery code instead**.
3. Select **Turn off two-factor**.

Signing in goes back to your password alone, and Coritan deletes your recovery codes. You can turn it on again at any time.

## Result

While it is on, the **Two-factor authentication** card shows **On**, the **Method** (**Authenticator app**), the date it was **Turned on** and how many **Recovery codes** you have left. Every sign-in now asks for a code after the password, and Coritan emails you when you turn it on or off.

Browsers and scripts that are already signed in stay signed in. To make each of them sign in again with a code, [change your password](/account/password/).

## Troubleshooting

`That code is not right`
: The code is wrong, or it was used already. Wait for the app to show the next code and type that. If every code fails, set your phone's clock to set itself automatically: the codes depend on the time.

`The password is not right`
: The password in **Turn off two-factor authentication** is wrong.

`Too many requests for this action. Please wait and try again.`
: You tried more than ten codes in five minutes. Wait a few minutes.

**Could not start setting up two-factor**
: The QR code did not load. Select **Try again**.

`Two-factor is already on; turn it off before setting up again`
: Two-factor authentication is on already, perhaps from another tab. Reload the page. To move it to a new phone, turn it off and set it up again.

You lost your phone
: Sign in with a recovery code, turn two-factor authentication off, then set it up on the new phone. Without a recovery code, [contact support](/support/).

## Related

- [Sign in to your account](/account/sign-in/)
- [Change or reset your password](/account/password/)
- [Link your account to a Coritan staff account](/account/staff-link/), which needs two-factor authentication

## With the API

Every call below takes your access token. Codes are six digits from the app, or a recovery code of the form `XXXX-XXXX-XX`. All the calls that check a code share one budget of ten tries in five minutes; the eleventh answers `429` with `"error": "rate_limited"`.

Read the state with [`GET /auth/mfa`](/api/reference/client/authentication-mfa/#op-get-api-v1-auth-mfa):

```json
{"enabled": true, "enabled_at": "2026-09-16T10:02:11", "recovery_codes_left": 8, "session_pending": false}
```

`session_pending` is `true` when the request used the pending token from a sign-in that still needs its code.

Turn it on in two calls:

1. [`POST /auth/mfa/setup`](/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-setup), with no body, answers with a new `secret`, its `otpauth_uri`, a QR code as `qr_svg`, the `issuer` (`Coritan`) and the `account` (your email). Add the secret to your app. Calling it again before step 2 replaces the secret.

   ```bash
   curl -X POST https://api.coritan.com/api/v1/auth/mfa/setup \
     -H "Authorization: Bearer $CORITAN_TOKEN"
   ```

2. [`POST /auth/mfa/enable`](/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-enable) with the first code from the app:

   ```bash
   curl -X POST https://api.coritan.com/api/v1/auth/mfa/enable \
     -H "Authorization: Bearer $CORITAN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"code": "123456"}'
   ```

   ```json
   {"enabled": true, "enabled_at": "2026-09-16T10:02:11", "recovery_codes": ["ABCD-EFGH-JK", "..."]}
   ```

   `recovery_codes` holds the ten codes. The API never shows them again.

Make new recovery codes with [`POST /auth/mfa/recovery-codes`](/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-recovery-codes) and `{"code": "123456"}`. It answers `{"recovery_codes": [...]}`, and the old codes stop working.

Turn it off with [`POST /auth/mfa/disable`](/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-disable) and `{"password": "your password", "code": "123456"}`. It answers `{"enabled": false}`.

[`POST /auth/mfa/verify`](/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-verify) finishes a sign-in, as [Sign in to your account](/account/sign-in/#with-the-api) shows. Called with a normal access token, it checks a code and answers `{"ok": true, "how": "totp", "recovery_codes_left": 8}`. A recovery code checked this way is used up.

| Status | `detail` | Meaning |
| --- | --- | --- |
| `400` | `That code is not right` | The code is wrong or already used. `POST /auth/mfa/verify` answers `401` for this. |
| `400` | `Start with setup before confirming a code` | `enable` came before `setup`. |
| `409` | `Two-factor is already on; turn it off before setting up again` | `setup` on an account that has it on. |
| `409` | `Two-factor is already on` | `enable` on an account that has it on. |
| `400` | `Two-factor is not on` | `disable` or `recovery-codes` on an account that has it off. `verify` answers `Two-factor is not on for this account`. |
| `400` | `The password is not right` | `disable` was sent the wrong password. |

## API

- `GET /api/v1/auth/mfa`: User MFA status (https://docs.coritan.com/api/reference/client/authentication-mfa/#op-get-api-v1-auth-mfa)
- `POST /api/v1/auth/mfa/setup`: User MFA setup (https://docs.coritan.com/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-setup)
- `POST /api/v1/auth/mfa/enable`: User MFA enable (https://docs.coritan.com/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-enable)
- `POST /api/v1/auth/mfa/verify`: Second step of signing in (https://docs.coritan.com/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-verify)
- `POST /api/v1/auth/mfa/recovery-codes`: User MFA regenerate recovery codes (https://docs.coritan.com/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-recovery-codes)
- `POST /api/v1/auth/mfa/disable`: User MFA disable (https://docs.coritan.com/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-disable)