> ## Documentation Index
> Fetch the complete documentation index at: https://safia.maximusolution.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAFIA Admin: User Management and Bot Access Control

> Browse registered Telegram accounts, switch between open and allowlist access modes, and update SAFIA's live configuration from the Settings page.

The Users and Settings pages give you full visibility into who is using SAFIA and complete control over who is allowed to. You can browse every registered account, restrict access to a curated list of Telegram user IDs, and update configuration values — all without restarting the bot or editing files directly.

## Viewing the user list

Navigate to **Users** (`/users`) to see every Telegram account that has interacted with your bot. The table shows the following columns for each account:

| Column      | Description                                            |
| ----------- | ------------------------------------------------------ |
| User        | Display name and avatar initial                        |
| Handle      | Telegram username (e.g. `@alice`), if set              |
| Status      | `active` (used the bot recently) or `idle`             |
| Records     | Total number of financial records the user has created |
| Joined      | Date the account was first registered                  |
| Telegram ID | The numeric Telegram user ID                           |

You can use this list to identify user IDs before adding them to the allowlist (see below).

## Access control modes

SAFIA supports two access modes, configurable from the **Settings** page (`/settings`):

<CardGroup cols={2}>
  <Card title="All Users" icon="globe">
    Any Telegram user who messages your bot can interact with it. This is the default mode — suitable for personal use or small, trusted groups.
  </Card>

  <Card title="Allowlist Only" icon="lock">
    Only Telegram user IDs explicitly added to the allowlist can use the bot. All other users receive a rejection message that includes their numeric Telegram ID.
  </Card>
</CardGroup>

<Tip>
  If you are deploying SAFIA for a specific household, team, or closed group, switch to **Allowlist only** mode. It prevents unintended usage and keeps your LLM token costs predictable.
</Tip>

## Switching access modes

<Steps>
  <Step title="Open Settings">
    In the dashboard sidebar, click **Settings** to navigate to `/settings`.
  </Step>

  <Step title="Select a mode">
    Under the **Access Control** card, click either **All users** or **Allowlist only**. The change is saved immediately — no restart required.
  </Step>
</Steps>

## Managing the allowlist

### Adding a user

<Steps>
  <Step title="Find the Telegram ID">
    Ask the person to open Telegram and send `/start` to **@userinfobot**. The bot replies instantly with their numeric Telegram ID (for example, `123456789`). Alternatively, if they already tried to message your SAFIA bot while it is in allowlist mode, the rejection message includes their ID.
  </Step>

  <Step title="Open Settings">
    Navigate to **Settings** (`/settings`) in the admin dashboard.
  </Step>

  <Step title="Enter the ID">
    In the **Allowed Telegram IDs** section, type the numeric ID into the input field and click **Add**. The ID appears in the list immediately.
  </Step>
</Steps>

### Removing a user

On the **Settings** page, find the ID in the **Allowed Telegram IDs** list and click **Remove** next to it. The user loses access immediately — no restart required.

<Note>
  The allowlist only takes effect when the access mode is set to **Allowlist only**. If you are in **All users** mode, the allowlist is stored but not enforced.
</Note>

## Editing configuration values

The **Settings** page also contains a full `.env` editor, organized into collapsible sections:

<Accordion title="Available configuration sections">
  | Section             | Example variables                                          |
  | ------------------- | ---------------------------------------------------------- |
  | Bot                 | `TELEGRAM_BOT_TOKEN`                                       |
  | AI & Voice          | `LLM_PROVIDER`, `LLM_API_KEY`, `LLM_MODEL`, `GROQ_API_KEY` |
  | Search & Data       | `FIRECRAWL_API_KEY`, `COINGECKO_API_KEY`                   |
  | Storage             | `DATABASE_URL`, `CACHE_DB_PATH`                            |
  | Vector & Embeddings | `QDRANT_PATH`, `EMBEDDING_LOCAL`, `EMBEDDING_LOCAL_MODEL`  |
  | Knowledge Base      | `KB_CHUNK_WORDS`, `KB_MAX_UPLOAD_MB`                       |
  | Reminders           | `REMINDER_ENABLED`, `REMINDER_MAX_PER_USER`                |
  | Admin               | `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `FLASK_SECRET_KEY`     |
</Accordion>

To edit a value:

<Steps>
  <Step title="Expand a section">
    Click the section header (e.g. **AI & Voice**) to expand it and reveal its variables.
  </Step>

  <Step title="Click Edit">
    Click the **Edit** button next to the variable you want to change. An input field appears inline.
  </Step>

  <Step title="Enter the new value">
    Type the new value and click **Save**. The `.env` file is updated on disk immediately, preserving all comments and other entries.
  </Step>

  <Step title="Restart the bot">
    Most configuration changes require a restart to take effect. Run `safia restart` from your terminal after saving.
  </Step>
</Steps>

<Warning>
  Sensitive values — any variable whose name ends in `_KEY`, `_TOKEN`, `_PASSWORD`, or `_SECRET` — are **masked** in the UI (shown as `abc12345...`). To update a sensitive value, click **Edit** and type the full new value. If you leave the field as the masked placeholder without changing it, SAFIA skips the update and keeps the existing value.
</Warning>