Source: https://help.spamfoo.com/guides/roles
Last updated: 2026-10-27

***

# Manage Sign-In and Roles

This page explains how people sign in to the SpamFoo Dashboard, what each role can see and change, and how to reach the dashboard from another computer.

## Understand the Three Roles

| Role | What They See |
| --- | --- |
| **System Admin** | The full [admin console](https://help.spamfoo.com/guides/admin-console): all domains, Messages and Senders for the whole server, System Spam Rules, Anti-Phishing for any domain, and the System pages (Status, Settings, and Logs). |
| **Domain Admin** | Their own mailbox (Overview, My Messages, and My Rules) plus a **Domain Admin** menu for their domain: Domain Overview, Mailboxes, Rules, and Anti-Phishing. See [Manage a Domain](https://help.spamfoo.com/guides/manage-domain). |
| **User** | Their own mailbox only: Overview, My Messages, and My Rules. See [Read Your Overview](https://help.spamfoo.com/guides/overview). |

A Domain Admin can see the totals for every mailbox in the domain, but can't open another person's messages.

## How Sign-In Works

- **With SmarterMail:** people sign in to SmarterMail and open the SpamFoo Dashboard from there. SmarterMail tells SpamFoo who they are and gives them a role. SmarterMail system administrators become System Admins, domain administrators become Domain Admins, and everyone else is a User. See [Open Your Dashboard](https://help.spamfoo.com/guides/open-dashboard).
- **With the proxy secret:** the proxy secret is a long random password that SpamFoo Client keeps in a file on the server. Anyone who signs in with it is a System Admin.
- **With a sign-in link:** a System Admin, or a script that has the proxy secret, makes a one-time link for a System Admin, a Domain Admin of one or more domains, or a User with one mailbox. Whoever opens the link gets that role. See [Give Someone a Sign-In Link](https://help.spamfoo.com/guides/roles#sign-in-links).

Opening the dashboard on the server itself does not skip sign-in. Requests from the same machine still need the proxy secret or a sign-in link.

## Sign In Without SmarterMail

1. On the server running SpamFoo Client, open `http://localhost:16253/admin/` in a browser. The **Sign in to SpamFoo** page appears.
2. Open the file `etc/sf.proxysecret` inside the SpamFoo data directory and copy its contents. With the Linux package, the file is `/var/lib/spamfoo/etc/sf.proxysecret`. With Docker, print it with this command:

   ```
   docker exec spamfoo-client cat /data/etc/sf.proxysecret
   ```
3. Paste the value into **Proxy secret**.
4. Click **Sign in**.

The browser sends the secret once and gets a sign-in cookie in return, so the secret isn't stored in the browser. The sign-in lasts 24 hours and is renewed while you use the dashboard. To sign out, click the role button at the top right and choose **Log out**.

If the page shows **That secret did not work**, check that you pasted the whole value. Older versions of SpamFoo Client saved the secret in the browser. The first time you open the dashboard after an update, it signs you in with that saved secret and then deletes it. If the secret has changed since, the page shows **Saved secret no longer works**, and you paste the new value.

In standalone mode, too many wrong secrets or bad sign-in links from one IP address in a short time block that address for a while. See [Requests Fail With a 429 Error](https://help.spamfoo.com/guides/common-problems#error-429).

> **Warning** Treat the proxy secret like a password. Anyone who has it gets full System Admin access to the dashboard.

### Give Someone a Sign-In Link

A sign-in link lets someone open the dashboard without the proxy secret, with only the access you choose. Make one on the server with [`spamfoo-client login-link`](https://help.spamfoo.com/guides/commands#login-link):

```
sudo spamfoo-client login-link --role=DomainAdmin --domain=example.com
```

Scripts and other programs that have the proxy secret can make links with the API. See [Create a Sign-In Link](https://help.spamfoo.com/api/login-link).

- **System Admin:** the full admin console.
- **Domain Admin:** the Domain Admin menu for the domains in the link. With more than one domain, a **Domain** picker appears at the top of the dashboard. If the link also names a mailbox, the person sees that mailbox's My Email menu too.
- **User:** the My Email menu for the mailbox in the link.

When someone opens the link, a page asks them to click **Continue**. The link is used up only when they click it, so a mail scanner that opens links in advance doesn't use it. Each link works once and expires after 15 minutes unless you choose a different time.

If the link has expired, was already used, or stopped working because the proxy secret changed, the page says **This sign-in link cannot be used**. Make a new link.

### Choose Your Own Secret

When SpamFoo Client starts and has no secret, it makes a random one and saves it to `etc/sf.proxysecret`. To use a value you choose instead, set the `SPAMFOO_PROXY_SECRET` environment variable before SpamFoo Client starts. This is the easiest way to keep a known secret for a Docker container. Use at least 32 characters. See [Proxy Secret](https://help.spamfoo.com/guides/configure#proxy-secret).

### Change the Secret

Change the secret if you think someone else may have it.

- **If you set `SPAMFOO_PROXY_SECRET`:** set it to a new value and restart SpamFoo Client.
- **In standalone mode:** run [`spamfoo-client rotate-secret`](https://help.spamfoo.com/guides/commands#rotate-secret), or put a new value in `etc/sf.proxysecret`. The running service picks it up within a few seconds, with no restart.
- **In embedded mode:** stop SpamFoo Client, delete `etc/sf.proxysecret`, and start it again. A new secret is created.
- **If you use SmarterMail:** SmarterMail creates and manages this file. Do not change or delete it yourself.

When the secret changes, everyone signed in to the dashboard is signed out, and unused sign-in links stop working.

If a mail server sends messages to SpamFoo Client, give it the new secret. In standalone mode, the old secret keeps working for mail for 15 minutes, so you have time to update it.

## View as Another Role

A System Admin can switch the dashboard to show exactly what a Domain Admin or User sees. This helps with support and with checking that rules apply the way you expect. Only System Admins can do this.

1. Click the role button at the top right.
2. Choose **Domain Admin** or **User**.
3. In the dialog, select a domain. For a user, select the domain first and then the user.
4. Click **OK**.

The role button now shows the role and the domain or user you are viewing. To go back, click the role button and choose **System Admin**.

You can also switch from other pages:

- On **Overview > Domains**, right-click a domain and choose **View as Domain Admin**.
- On a domain's details page, click **View as Domain Admin**.
- In the **Mailboxes** list on a domain's details page, right-click a mailbox and choose **View as User**.

When you view as a Domain Admin, only the Domain Admin menu appears, because you are viewing a domain and not a specific mailbox.

## Know Who Can Change What

| What | Who Can Change It |
| --- | --- |
| System Spam Rules (every domain) | System Admin only |
| Domain Spam Rules | System Admin, or a Domain Admin of that domain |
| A mailbox's own Spam Rules | System Admin, or the owner of that mailbox |
| Protected identities and delegated senders | System Admin, or a Domain Admin of that domain |
| System Status, Settings, Logs, and updates | System Admin only |

## Set Up Remote Access

If you use SmarterMail, there is nothing to set up. SmarterMail passes dashboard requests on to SpamFoo Client, so people reach the dashboard through SmarterMail's web interface from any computer that can reach SmarterMail.

Without SmarterMail, you need something to do that job. To open the dashboard from your own computer, put a reverse proxy, such as Nginx or Caddy, in front of SpamFoo Client. A reverse proxy is a web server that accepts the connection and passes it on to SpamFoo Client.

> **Warning** Do not open port 16253 to the internet.

Set up the reverse proxy so it:

- **Uses HTTPS (TLS).** The proxy secret is sent with every request, so it must be encrypted on the network.
- **Passes on only the `/admin/` path.** In embedded mode, SpamFoo Client treats requests from the same machine as trusted for classifying mail. If the proxy passes on every path, anyone who can reach the proxy can send it messages to classify.
- **Limits who can connect.** Allow only your admin network or VPN, and add the proxy's own sign-in if you can.

People still sign in to the dashboard with the proxy secret or a sign-in link after they get through the proxy. In standalone mode, set [`SPAMFOO_PUBLIC_URL`](https://help.spamfoo.com/guides/configure#public-url) to the proxy's address, such as `https://spamfoo-admin.example.com`, so sign-in links made on the server point to it.

Every request through a proxy on the same server comes from the same address. In standalone mode, too many failed sign-ins through the proxy block that address, and so everyone who uses the proxy, for a while.

Here are examples for Nginx and Caddy. Replace the server name, certificate paths, and network range with your own.

### Nginx

```
server {
    listen 443 ssl;
    server_name spamfoo-admin.example.com;

    ssl_certificate     /etc/ssl/certs/spamfoo-admin.crt;
    ssl_certificate_key /etc/ssl/private/spamfoo-admin.key;

    allow 10.0.0.0/8;
    deny all;

    location /admin/ {
        proxy_pass http://127.0.0.1:16253;
        proxy_set_header Host $host;
        proxy_buffering off;
    }
}
```

`proxy_buffering off` lets the live numbers on **System > Status** update as they change.

### Caddy

```
spamfoo-admin.example.com {
    tls /etc/ssl/certs/spamfoo-admin.crt /etc/ssl/private/spamfoo-admin.key

    @admin {
        remote_ip 10.0.0.0/8
        path /admin/*
    }

    handle @admin {
        reverse_proxy 127.0.0.1:16253 {
            flush_interval -1
        }
    }

    handle {
        respond 403
    }
}
```

`flush_interval -1` lets the live numbers on **System > Status** update as they change. If the server name is reachable from the internet, you can leave out the `tls` line and Caddy gets a certificate for you.

### Docker

The Docker image listens on all network interfaces so your mail server can reach it. Publish port 16253 only to your mail server's network, or keep the container behind a firewall.