# Account & authentication

Guides for signing in, registering, and managing your HarborFM account.

## Login and registration

### Signing in

1. Open the HarborFM login page (e.g. `/login` or the "Sign in" link).
2. Enter your **email** and **password**.
3. If you have two-factor authentication enabled, you'll be prompted for your 2FA code after the password. See [Two-factor auth](#two-factor-authentication-2fa).

After a successful login you're taken to the dashboard.

**Troubleshooting:** If you see "Server not set up yet," the instance hasn't been initialized. Open the one-time setup URL from the server logs. See [Getting started](Getting-started.md). For repeated failed logins, the server may temporarily ban your IP; see [Troubleshooting](Admin-and-settings.md#troubleshooting) and the main [README](../blob/main/README.md).

---

### Registration

Whether new users can create accounts is controlled by the instance admin in **Settings**. If **account registration** is enabled:

1. Open the **Register** link from the login page.
2. Enter email, username (if required), and password.
3. Complete any verification step (e.g. email verification) if the instance has it enabled.
4. Sign in with your new account.

If registration is disabled, only existing users (or users invited by an admin or collaborator) can use the instance.

---

### See also

- [Two-factor auth](#two-factor-authentication-2fa)
- [Password reset](#password-reset)
- [Profile and API keys](#profile-and-api-keys)
- [Getting started](Getting-started.md)

## Two-factor authentication (2FA)

Two-factor authentication adds a second step when you sign in: after entering your password, you enter a code from an authenticator app (or similar).

### Enabling 2FA

1. Sign in and go to your **Profile** (or account/settings).
2. Find the **Two-factor authentication** section.
3. Follow the steps to enable 2FA: the app will show a QR code (or a secret key) to add to your authenticator app (e.g. Google Authenticator, Authy).
4. Scan the code or enter the key, then enter a verification code from the app to confirm.
5. Save any backup codes if the app offers them; use them to sign in if you lose access to the authenticator.

Once 2FA is enabled, each login will require your password plus a current code from the app.

### Signing in with 2FA

1. Enter your email and password on the login page.
2. When prompted, enter the 6-digit code from your authenticator app.
3. Complete sign-in.

### Disabling 2FA

From your **Profile**, open the two-factor authentication section and choose to disable 2FA. You may need to enter your password or a current 2FA code to confirm.

### See also

- [Login and registration](#login-and-registration)
- [Profile and API keys](#profile-and-api-keys)

## Password reset

If you forgot your password, you can request a reset link by email (when the instance has email configured).

### Requesting a reset

1. On the **login** page, use the "Forgot password?" (or similar) link.
2. Enter the **email** associated with your account.
3. Submit the form. If that email exists, the server sends a password-reset link (subject to the instance's email and rate-limit settings).
4. Check your inbox (and spam folder). The link is valid for a limited time (e.g. one hour; see the main [README](../blob/main/README.md) for `RESET_TOKEN_EXPIRY_HOURS`).
5. Open the link and set a **new password**, then sign in with it.

If you don't receive an email, confirm the address is correct and that the instance has email (SMTP) configured. Admins can also reset a user's password from **Users**; see [User management](Admin-and-settings.md#user-management).

### See also

- [Login and registration](#login-and-registration)
- [User management](Admin-and-settings.md#user-management) (admin: reset another user's password)

## Profile and API keys

### Profile page

From your **Profile** you can:

- View and update your **email** and **username** (subject to rate limits and instance settings).
- Manage **two-factor authentication**; see [Two-factor auth](#two-factor-authentication-2fa).
- View and manage **API keys** (below).

Changes to email or username may require verification depending on instance configuration.

### API keys

API keys let you call the HarborFM API (e.g. from scripts or other apps) without using a browser session. The API is documented via Swagger; when running your own instance, the docs are typically at `https://your-host/api/docs`.

#### Creating an API key

1. Open your **Profile**.
2. Find the **API keys** section.
3. Click to **create** a new key. Give it a label if the UI allows (e.g. "CI" or "Upload script").
4. **Copy the key** immediately; it may be shown only once. Store it securely (e.g. in a secrets manager or env var).

Use the key in API requests as required by the server (often a header such as `Authorization: Bearer <key>` or an API-key header; check the Swagger docs for your version).

#### Managing API keys

- You can **list** and **revoke** keys from the Profile page.
- Revoking a key invalidates it immediately; any script or app using that key will get unauthorized errors until updated with a new key.
- The server may limit how many keys you can have per account; see the main [README](../blob/main/README.md) for `MAX_API_KEYS_PER_USER`.

### Disabling your account

At the bottom of your **Profile** page, a **Disable Account** card lets you disable your own account. For password accounts you'll be asked to confirm with your password; for federated (SSO) accounts you'll see an "Are you sure?" confirmation. **Two-factor authentication must be disabled first** before you can disable the account. Read-only accounts and the sole admin on the instance cannot disable their account. After you disable, you are signed out.

### See also

- [Two-factor auth](#two-factor-authentication-2fa)
- [Login and registration](#login-and-registration)
- Main [README](../blob/main/README.md) - environment variables for auth (e.g. JWT, API key prefix)