# Secure a mailbox

> Create app passwords for mail apps, turn on two-factor sign-in for a mailbox, and end its webmail sessions.

Source: https://www.coritan.com/docs/mail/mail-hosting/mailbox-security/

In the dashboard:

- /dashboard/mail/…/mailboxes: https://www.coritan.com/dashboard/mail

Each mailbox on a Mail Hosting service has three controls that decide who can sign in to it: *app passwords* for mail apps, *two-factor sign-in* with an authenticator app, and the list of browsers signed in to webmail. You reach all three from the mailbox's menu on the **Mailboxes** tab. The mailbox's own user can manage the same things in webmail; see [Protect your webmail mailbox](/docs/mail/webmail/security/).

## Before you begin

- A mailbox on a Mail Hosting service. See [Create and manage mailboxes](/docs/mail/mail-hosting/mailboxes/).
- For two-factor sign-in, an authenticator app on a phone or computer. Any app that reads an `otpauth://` link or takes a key by hand works.

## Create an app password

An app password signs one mail app in to the mailbox in place of its password, and skips the two-factor code. Give each app its own, so you can revoke one without touching the others.

1. In the dashboard, go to [**Email**](https://www.coritan.com/dashboard/mail), open the Mail Hosting service, then the **Mailboxes** tab.
2. Open the menu at the end of the mailbox's row and select **App passwords…**.
3. Optionally, enter a **Label** that names the app or device, such as `phone`. It can be up to 64 characters.
4. Select **Create app password**.
5. Copy the **App password** from the dialog that opens. We show it once and cannot show it again.

In the mail app, use the mailbox's address as the username and the app password as the password. The mailbox's **Security** column counts its app passwords, such as `2 app passwords`.

A mailbox holds at most ten app passwords. Each browser signed in to webmail uses one of them, so the more browsers are signed in, the fewer you can create.

## Revoke an app password

1. On the **Mailboxes** tab, open the menu at the end of the mailbox's row and select **App passwords…**.
2. Find the password by its label. Each row also shows the date it was created.
3. Select **Revoke…**, then **Revoke app password**.

The app that used it can no longer sign in. The list also shows the passwords the mailbox's user made in webmail for their devices, and revoking one here signs that device out too.

## Turn on two-factor sign-in

With two-factor sign-in on, webmail asks for a six-digit code from an authenticator app after the password.

1. On the **Mailboxes** tab, open the menu at the end of the mailbox's row.
2. Select **Turn on two-factor sign-in**.
3. From the dialog that opens, add the mailbox to the authenticator app: open the **otpauth URI** on the device with the app, or type the **Secret** into it. We show them once. The app lists the mailbox under the service's mail server name, such as `mail-fra.coritan.com`.

The **Security** column changes to **Two-factor on**, and every browser signed in to webmail is signed out. The next time someone signs in, webmail shows **Enter your code** after the password and takes the code in **Code**. Codes change every 30 seconds.

Mail apps cannot ask for a code. A mail app that signed in with the mailbox's password stops working until you give it an [app password](#create-an-app-password). App passwords made before you turned two-factor sign-in on keep working.

## Turn off two-factor sign-in

To turn off two-factor sign-in from the dashboard, give the mailbox a new generated password:

1. On the **Mailboxes** tab, open the menu at the end of the mailbox's row.
2. Select **Reset password…**.
3. Choose **Generate a strong password**, then select **Reset password**.
4. Copy the new password from the dialog and give it to the mailbox's user.

The mailbox goes back to signing in with the password alone. Reload the page to see **Two-factor off** in the **Security** column. Resetting the password also signs the mailbox out of webmail everywhere; its app passwords keep working.

The mailbox's user can turn it off without a new password. In [webmail](https://www.coritan.com/webmail), signed in with the mailbox's address, they turn off **Ask for a code when signing in** on the **Security** tab of settings and confirm with the mailbox's password. [Turn off two-factor authentication](/docs/mail/webmail/security/#turn-off-two-factor-authentication) explains what changes when they open the mailbox through a Coritan account instead.

> [!NOTE]
> The mailbox menu also shows **Turn off two-factor sign-in…** while two-factor sign-in is on. It needs the mailbox's password, which the dashboard does not ask for, so it always ends with `Could not turn off two-factor sign-in`. Reset the password as above instead.

## End webmail sessions

A *webmail session* is one browser signed in to webmail as the mailbox. End one when a device is lost, or when someone should no longer read the mailbox.

1. On the **Mailboxes** tab, open the menu at the end of the mailbox's row and select **Webmail sessions…**.
2. Read the list. Each row names the browser and system, such as `Firefox on Windows`, then the IP address, when it was last used and when it started. Hover over the name to see the browser's full description.
3. To sign out one browser, select **End session…** on its row, then **End session**.
4. To sign out every browser, select **Sign out everywhere…**, then **Sign out everywhere**.

The browser has to sign in again with the mailbox's address and password. Ending sessions does not change the password, so anyone who knows it can sign in again: to lock someone out, [reset the password](/docs/mail/mail-hosting/mailboxes/#reset-a-mailbox-password) as well. Mail apps keep working, because they use the password or an app password rather than a session.

A session also ends by itself:

- after 30 days, or after 7 days without use;
- when a sixth browser signs in to the mailbox, which ends the one used longest ago;
- when you reset the password, turn two-factor sign-in on or off, or turn the mailbox off or delete it.

## Troubleshooting

`Turning two-factor login off needs the mailbox password; reset the password to clear it instead`
: **Turn off two-factor sign-in…** cannot work from the dashboard. [Reset the password](#turn-off-two-factor-sign-in) with a generated one, or ask the mailbox's user to turn it off in webmail.

A mail app stopped signing in after two-factor sign-in went on
: The app signs in with the mailbox's password, which now needs a code the app cannot send. [Create an app password](#create-an-app-password) and enter it in the app in place of the password.

`Mail engine error: AppPassword not created`
: The mail server refused to make the password. The mailbox may already hold ten app passwords, counting one for each browser signed in to webmail. Revoke one you no longer use, or end a webmail session, then try again.

`Mailbox is not registered in the engine yet`
: The mailbox was created moments ago and its setup has not finished. Wait a minute, then try again.

A browser keeps being signed out of webmail
: A mailbox keeps at most five webmail sessions, so signing in on a sixth browser ends the one used longest ago. A password reset, a two-factor change and turning the mailbox off end every session.

**No one is signed in to the webmail**
: No browser holds a session for the mailbox. Mail apps never appear in this list.

## Related

- [Create and manage mailboxes](/docs/mail/mail-hosting/mailboxes/)
- [Connect a mail app to Mail Hosting](/docs/mail/mail-hosting/connect-a-mail-app/)
- [Protect your webmail mailbox](/docs/mail/webmail/security/)

## With the API

All the paths below sit under `/client/mail/{service_id}/mailboxes/{account_id}`, where `account_id` is the mailbox's `id` from `GET /client/mail/{service_id}/mailboxes`.

Create an app password:

```bash
curl -X POST https://api.coritan.com/api/v1/client/mail/4812/mailboxes/5120/app-passwords \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "phone"}'
```

`label` is 1–64 characters and defaults to `app password`. The answer is `201`, and `secret` is the password, returned this once:

```json
{
  "id": 5120,
  "address": "alex@example.com",
  "credential_id": "b7",
  "label": "phone",
  "secret": "k3Vd9QxT2mLw7RpZ"
}
```

Turn on two-factor sign-in:

```bash
curl -X POST https://api.coritan.com/api/v1/client/mail/4812/mailboxes/5120/totp \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

The answer carries the `secret` and the `otpauth_uri` once. The URI names SHA-1, six digits and a 30-second period, and its issuer is the service's mail server name:

```json
{
  "id": 5120,
  "address": "alex@example.com",
  "otpauth_uri": "otpauth://totp/mail-fra.coritan.com%3Aalex%40example.com?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=mail-fra.coritan.com&algorithm=SHA1&digits=6&period=30",
  "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP"
}
```

The other operations:

| Operation | Answer |
| --- | --- |
| `GET .../app-passwords` | `{"items": [...]}`, each with `credential_id`, `label`, `created_at` and `expires_at`. Webmail sessions are not listed. |
| `DELETE .../app-passwords/{credential_id}` | `{"deleted": true}`, or `404` `App password not found` |
| `DELETE .../totp` | Always `400` `Turning two-factor login off needs the mailbox password; reset the password to clear it instead`. Send `{}` to `POST .../password` instead. |
| `GET .../sessions` | `{"items": [...]}`, most recently used first |
| `DELETE .../sessions/{session_id}` | `204`, or `404` `Session not found` |
| `DELETE .../sessions` | `204`, after ending every session |

Each session in `GET .../sessions` has these fields:

`id`
: The session's id, for `DELETE .../sessions/{session_id}`.

`created_at`, `last_used_at`
: When it signed in and when it was last used, in UTC.

`expires_at`
: When it ends if nobody uses it from now on: 7 days after `last_used_at`, and never more than 30 days after `created_at`.

`ip`, `user_agent`
: The IP address and the browser's own description of itself.

An `account_id` that is not a mailbox on the service answers `404` `Not found`, and a failure on our side answers `502` with a message that starts `Mail engine error:`.

## API

- `GET /api/v1/client/mail/{service_id}/mailboxes/{account_id}/app-passwords`: Mailbox app passwords (https://www.coritan.com/docs/api/reference/client/mail/mail-mailboxes/#op-get-api-v1-client-mail-service-id-mailboxes-account-id-app-passwords)
- `POST /api/v1/client/mail/{service_id}/mailboxes/{account_id}/app-passwords`: Mailbox app password create (https://www.coritan.com/docs/api/reference/client/mail/mail-mailboxes/#op-post-api-v1-client-mail-service-id-mailboxes-account-id-app-passwords)
- `DELETE /api/v1/client/mail/{service_id}/mailboxes/{account_id}/app-passwords/{credential_id}`: Mailbox app password delete (https://www.coritan.com/docs/api/reference/client/mail/mail-mailboxes/#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-app-passwords-credenti)
- `POST /api/v1/client/mail/{service_id}/mailboxes/{account_id}/totp`: Mailbox totp enable (https://www.coritan.com/docs/api/reference/client/mail/mail-mailboxes/#op-post-api-v1-client-mail-service-id-mailboxes-account-id-totp)
- `DELETE /api/v1/client/mail/{service_id}/mailboxes/{account_id}/totp`: Mailbox totp disable (https://www.coritan.com/docs/api/reference/client/mail/mail-mailboxes/#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-totp)
- `GET /api/v1/client/mail/{service_id}/mailboxes/{account_id}/sessions`: Mailbox sessions (https://www.coritan.com/docs/api/reference/client/mail/mail-mailboxes/#op-get-api-v1-client-mail-service-id-mailboxes-account-id-sessions)
- `DELETE /api/v1/client/mail/{service_id}/mailboxes/{account_id}/sessions`: Mailbox sessions end (https://www.coritan.com/docs/api/reference/client/mail/mail-mailboxes/#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-sessions)
- `DELETE /api/v1/client/mail/{service_id}/mailboxes/{account_id}/sessions/{session_id}`: Mailbox session end (https://www.coritan.com/docs/api/reference/client/mail/mail-mailboxes/#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-sessions-session-id)