Turn on two-factor authentication

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.

• Sign in to the 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.

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.

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.

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.

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.

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.

• Sign in to your account
• Change or reset your password
• Link your account to a Coritan staff account, which needs two-factor authentication

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:

{"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, 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.

   Shell

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

2. POST /auth/mfa/enable with the first code from the app:

   Shell

   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 and {"code": "123456"}. It answers {"recovery_codes": [...]}, and the old codes stop working.

Turn it off with POST /auth/mfa/disable and {"password": "your password", "code": "123456"}. It answers {"enabled": false}.

POST /auth/mfa/verify finishes a sign-in, as Sign in to your account 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.