Skip to content

Authentication

iongpt edited this page Nov 17, 2026 · 1 revision

Authentication

New in v2.4.0. Boxarr can ask for a sign-in before anyone uses it. Sign-in is optional, and it is off until you turn it on.

This page covers the sign-in methods, the API key, the widget token, every BOXARR_AUTH_* variable, the files Boxarr keeps, and how to get back in when you are locked out.

What's new in v2.4.0

  • Three methods: Off, Forms (Boxarr's own login page) and External (a reverse proxy that signs people in, such as Authelia or Authentik). There is no HTTP Basic auth.
  • Settings → Security: a new section at the bottom of the Settings page (/setup), with its own Save security settings button.
  • An API key for scripts, Homepage and Home Assistant, sent in a header.
  • Widgets stay public by default, and can be switched to need a token.
  • Environment variables (BOXARR_AUTH_*) for a setup without the UI.
  • Command-line tools: --hash-password and --auth-reset.
  • Health: while sign-in is on, an anonymous GET /api/health answers only {"status": "healthy"}. A signed-in browser, the API key, or a request through the trusted proxy (External) gets the full body. A dashboard that reads radarr_connected needs the API key. A monitor that probes / should probe /api/health, which needs no sign-in.

Upgrading

After an upgrade, and on a new install, sign-in is off. Boxarr behaves as before, except for a banner on its pages:

Boxarr is not protected. Anyone who can reach it can change Radarr. Set up a login in Settings → Security.

The banner has two buttons:

  • Set up login opens Settings → Security with the username field ready.
  • Keep it open saves your choice to leave sign-in off, and hides the banner. You can turn sign-in on later in Settings → Security.

The banner shows on Boxarr's full pages until you save a choice. It never shows in the widgets or on the login page.

While sign-in is off, after Keep it open too, anyone who can reach Boxarr can turn sign-in on with their own password. If that may have happened, see If someone else reached Boxarr first.

Choosing a method

Method In Settings → Security Who gets in
Off Off: anyone who can reach Boxarr can use it Everyone, as before v2.4.0
Forms On: sign in with a username and password A browser signed in on Boxarr's login page, and the API key
External External: your reverse proxy signs people in Requests that come through a trusted proxy, and the API key
  • Forms suits most installs. Boxarr has one username and one password.
  • External suits a reverse proxy that already signs people in (Authelia, Authentik, oauth2-proxy). Boxarr then trusts the connection from the proxy and shows no login page of its own.
  • Off leaves Boxarr open to anyone who can reach it.

Boxarr has no option to skip sign-in for local addresses. Behind Docker every client can look local, and a website you visit could reach Boxarr through DNS rebinding as if it were on your network.

Forms

Turning it on in Settings

  1. Open Settings (/setup) and scroll to Security, or click Set up login on the banner.
  2. Set Sign-in to On: sign in with a username and password.
  3. Enter a Username, a Password and Repeat the password.
  4. Optional: set Chart widgets, and open Reverse proxy, cookie and session length for Trusted proxies, Secure cookie, Sign-in lasts (hours) and Keep me signed in (days).
  5. Click Save security settings.

This browser stays signed in. Boxarr also makes an API key and shows it once, under Your new API key. Copy it, then click I have saved it: continue. If BOXARR_AUTH_API_KEY or BOXARR_AUTH_API_KEY_FILE is set, no key is made.

Rules:

  • The username is 1 to 64 characters. It is not case-sensitive at sign-in.
  • The password is at least 12 characters and at most 1024 bytes, and it must not be the username.

Turning sign-in on from Off always starts auth.json over: only its instance id and a new credential generation are kept, and a new API key is made (see If someone else reached Boxarr first).

While sign-in is on, every change in Settings → Security needs your Current password, including a new API key and Sign out everywhere. A new username or password signs out every other browser and device. This one stays signed in.

Turning it on by environment

Set the method, the username and one password variable, then restart Boxarr:

services:
  boxarr:
    image: ghcr.io/iongpt/boxarr:latest
    container_name: boxarr
    ports:
      - 8888:8888
    volumes:
      - ./config:/config
    environment:
      - BOXARR_AUTH_METHOD=forms
      - BOXARR_AUTH_USERNAME=owner
      - BOXARR_AUTH_PASSWORD_FILE=/run/secrets/boxarr_password
    secrets:
      - boxarr_password
    restart: unless-stopped

secrets:
  boxarr_password:
    file: ./boxarr_password.txt

For the password, use one of:

  • BOXARR_AUTH_PASSWORD_FILE: a file that holds the password, such as a Docker secret. Preferred.
  • BOXARR_AUTH_PASSWORD_HASH: a hash from --hash-password.
  • BOXARR_AUTH_PASSWORD: the password in plain text. Boxarr logs a warning, because docker inspect shows it.

Notes:

  • No API key is made this way. Create one in Settings → Security, or set BOXARR_AUTH_API_KEY_FILE.
  • At startup, a new password from the environment (one that does not match the stored one) is hashed into auth.json, and every session is signed out. The log says Authentication: applied the password from BOXARR_AUTH_PASSWORD_FILE; every session was signed out. Once stored, the password keeps working if you later remove the variable.
  • A field that a variable sets is read-only in Settings → Security and shows 🔒 Set by <variable>.
  • If the new password from the environment replaces one that was set in Settings → Security, auth.json starts over and every setting saved there is cleared. The same password moved into the environment changes nothing. See Passwords from the environment.

Signing in and out

  • Signed-out browsers are sent to /login, and back to the page they asked for after signing in.
  • Keep me signed in is ticked by default. See Sessions and cookies.
  • Sign out with the ⏻ button in the navigation bar, or ⏻ Sign out at the top of the Settings page.
  • When a session ends while a page is open, the page shows Your session has expired. Sign in again. It does not leave the page by itself, so unsaved input stays.

Wrong passwords are slowed down, never locked out:

  • From one address, the first 5 wrong passwords for a username within 15 minutes get an answer at once. After that, each attempt waits 1, 2, 4 and up to 30 seconds after the last failure.
  • An address with 20 failures within 15 minutes, across all usernames, waits the same way.
  • The answer is HTTP 429, Too many attempts, try again in N s.
  • A valid session or API key is never blocked. A restart clears the counts.
  • The Current password check in Settings → Security counts the same way.
  • Each failure is logged as Failed sign-in from <address>, a stable line for fail2ban. Behind a reverse proxy, the address is the browser's only when the proxy is in BOXARR_AUTH_TRUSTED_PROXIES.

External

Under External, a reverse proxy in front of Boxarr signs people in. Boxarr trusts the connection, not what it says:

  • A request whose connection comes from a trusted proxy passes. Boxarr reads no header for this: X-Forwarded-For, X-Real-IP, Forwarded and Remote-User can never make a request come from the proxy. Boxarr reads no user name from the proxy.
  • Any other address gets only the API key, the widgets and the health check. A page answers 403 "Open Boxarr through your proxy", which names the address the request came from. The API answers 403 JSON with X-Boxarr-Auth: proxy-required.
  • Boxarr has no login page and no sessions under External. Sign out in your proxy.

External needs an explicit list of trusted proxies, from BOXARR_AUTH_TRUSTED_PROXIES or from Trusted proxies in Settings. FORWARDED_ALLOW_IPS does not count. Without a usable list, Boxarr locks and names the fix.

Switching to External in Settings

  1. Turn Forms on first, and sign in through your proxy.
  2. Under Reverse proxy, cookie and session length, add the proxy's address to Trusted proxies. The Security section shows where your request came from, for example This request: from 192.168.1.20 via trusted proxy 172.20.0.5 (https).
  3. Set Sign-in to External, enter your current password and save.

The switch is refused if the request did not itself come through a trusted proxy, because the browser would then be shut out. It ends every Boxarr sign-in. External cannot be chosen while sign-in is off.

Setting External by environment

    environment:
      - BOXARR_URL_BASE=boxarr
      - BOXARR_AUTH_METHOD=external
      - BOXARR_AUTH_TRUSTED_PROXIES=172.20.0.5   # the proxy's address, as Boxarr sees it

A minimal nginx setup in front of it:

location /boxarr/ {
    auth_request /authelia;              # your proxy's own sign-in, set up as its docs say
    proxy_pass http://boxarr:8888;       # no URI after the port: keeps the /boxarr/ prefix
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Before you use External

  • Trust only an address that nothing but your proxy uses. Where Docker publishes Boxarr's port (ports: - 8888:8888), every client can arrive from the Docker gateway's address. Trusting the gateway then trusts everyone. Put the proxy and Boxarr on one Docker network and trust the proxy's address there. Do not publish Boxarr's port unless you need it, for example for the widgets (below), and never trust the gateway.
  • A proxy rule that skips its sign-in for /api/* opens the whole API to anyone who reaches the proxy, because every such request comes through the trusted proxy. Only changes under /api/auth/ stay guarded, and only by Boxarr's own password when one is set. Reading them is not guarded. Let scripts use the API key instead.
  • The widgets through the proxy. A request through the trusted proxy passes without a widget token, even when the widgets need one. A token that is sent must still be the right one. Boxarr cannot tell that the proxy skipped its sign-in, so if you let the two widget paths through the proxy without one, they are public, token or not. To keep the token, embed Boxarr's own address, one that does not go through the proxy: there, a request without the right token gets 401. With the widgets on Token, Settings → Security says so under the embed URLs: These URLs go through your reverse proxy, as this page does: embed Boxarr's own address instead.
  • A password under External. The username and password sign no one in. Once a password is set, it confirms every change in Settings → Security, the API key and widget token included. With no password set, anyone your proxy lets in can change the Security settings, set a password or make an API key. Set a password when your proxy admits more than one user.
  • A password variable under External (BOXARR_AUTH_PASSWORD_FILE, BOXARR_AUTH_PASSWORD or BOXARR_AUTH_PASSWORD_HASH) confirms the changes in place of one set in Settings. Under External it is never stored: remove the variable and the password in auth.json, if any, applies again.
  • A new password saved under External answers Saved. Settings → Security asks for the new password from now on., and a new username alone Security settings saved. No one is signed out: the proxy signs people in.
  • If the proxy's address changes (a recreated container), the 403 page and the log name the new address: Refused a request from <address>: external sign-in lets in only connections from the trusted proxies (BOXARR_AUTH_TRUSTED_PROXIES).

External over a sign-in set up in Settings

Under External, what was set up in Settings → Security still applies: its password, its API key, its widget token and its saved trusted proxies, unless a variable sets them. When BOXARR_AUTH_METHOD=external, BOXARR_AUTH_USERNAME or a password variable is set too, and something from Settings is still kept, every start logs a WARNING that names it (the trusted proxies with their addresses, never a secret). It has two forms. An External chosen in Settings with none of these variables logs nothing.

BOXARR_AUTH_METHOD=external while auth.json holds a sign-in set up in Settings:

Authentication: BOXARR_AUTH_METHOD=external, and auth.json still holds a sign-in set up in Settings → Security: a password, an API key. They still apply. If you did not set them up, someone who reached Boxarr while sign-in was off may have: run python -m src.main --auth-reset (in Docker: docker exec boxarr python -m src.main --auth-reset), keep BOXARR_AUTH_METHOD=external, set BOXARR_AUTH_TRUSTED_PROXIES to your proxy's address, and restart Boxarr.

If you did not set them up, do what it says. Set BOXARR_AUTH_TRUSTED_PROXIES, since the reset clears the saved list.

BOXARR_AUTH_USERNAME or a password variable, without BOXARR_AUTH_METHOD, while auth.json says External:

With a password variable:

Authentication: auth.json, set in Settings → Security, keeps sign-in external, so BOXARR_AUTH_USERNAME and BOXARR_AUTH_PASSWORD_FILE do not turn on Boxarr's login page, and an API key, the trusted proxies (172.20.0.5) still apply. If you did not set it up, someone who reached Boxarr while sign-in was off may have: set BOXARR_AUTH_METHOD=forms and restart Boxarr, and auth.json starts over with these credentials.

With BOXARR_AUTH_USERNAME alone:

Authentication: auth.json, set in Settings → Security, keeps sign-in external, so BOXARR_AUTH_USERNAME does not turn on Boxarr's login page, and a password, an API key, the trusted proxies (172.20.0.5) still apply. If you did not set it up, someone who reached Boxarr while sign-in was off may have: set BOXARR_AUTH_METHOD=forms and your own password in BOXARR_AUTH_PASSWORD_FILE and restart Boxarr, and auth.json starts over with that password.

If you did not set it up, do what it says. Under BOXARR_AUTH_METHOD=forms, the password from the environment replaces the one set in Settings, so auth.json starts over: the API key, the widget token and the trusted proxies are cleared. Settings → Security cannot make this switch while a password variable is set: choosing On there answers BOXARR_AUTH_PASSWORD_FILE is set: to use Boxarr's own sign-in with it, set BOXARR_AUTH_METHOD=forms and restart Boxarr.

Both forms name a password only when no password variable is set: a password variable wins over the stored one.

The API key

Scripts, Homepage and Home Assistant use the API key while sign-in is on. While sign-in is off, the API needs no key.

  • A key made by Boxarr starts with bxk_. It is shown once. Boxarr stores only its SHA-256, its last 4 characters (the hint shown in Settings, bxk_…AbCd) and when it was made.
  • Send it in a header:
    • X-Api-Key: bxk_EXAMPLE..., or
    • Authorization: Bearer bxk_EXAMPLE... (only a value that starts with bxk_ counts here).
  • Never in the URL. ?apikey= and ?api_key= are ignored, and the 401 says An API key in the URL is ignored: send it in the X-Api-Key header.
curl -H "X-Api-Key: bxk_EXAMPLE..." http://your-server:8888/api/boxoffice/current

What it opens:

  • API requests: GET on /api/... and /openapi.json, and any POST, PUT or DELETE.
  • The widgets, in either mode.
  • Not pages, and not the interactive docs at /api/docs: open those in a signed-in browser.
  • Never /api/auth/...: a key answers 403 API keys cannot manage authentication.

A wrong key answers 401 Invalid API key. with X-Boxarr-Auth: invalid-key, even next to a valid session or through the trusted proxy, so a script with an old key finds out. On /api/health and public widgets a wrong key is ignored. Wrong keys never count toward the sign-in throttle. Each address is logged as Invalid API key from <address> at most once every 10 minutes.

Managing it in Settings → Security → API key (each needs the current password):

  • Create an API key or Regenerate: the old key stops working at once. Update it wherever it is used.
  • Revoke: anything that still sends it is refused.

By environment: BOXARR_AUTH_API_KEY_FILE or BOXARR_AUTH_API_KEY sets the key, 32 to 1024 printable ASCII characters without spaces. It needs no bxk_ prefix, but a key without one works only in X-Api-Key. The API key part of Settings then shows 🔒 Set by <variable>.

Widgets

/api/widget (HTML) and /api/widget/json show this week's chart. Settings → Security → Chart widgets:

  • Public (the default): anyone who can reach Boxarr can read them, so a dashboard embeds the URLs as they are.
  • Token: while sign-in is on, a request needs the widget token in ?token=, a signed-in browser or the API key.

The token mode applies only while sign-in is on. While sign-in is off, the widgets are public whatever the setting.

The widget token:

  • Boxarr makes it when the widgets switch to Token with sign-in on, and on Create a widget token or Regenerate the token (current password needed). Regenerate stops the old one at once.
  • It is bxw_ followed by random characters. The Widgets part of Settings → Security shows both embed URLs with the token and your URL base, with Copy buttons, for example https://boxarr.example/boxarr/api/widget?token=bxw_EXAMPLE....
  • It opens these two routes and nothing else.
  • It is the one credential Boxarr reads from a URL. Anyone who has the URL can read this week's chart: if it leaks, regenerate it. The access log shows token=[redacted].
  • A missing or wrong token answers 401 in the widget's own format (HTML or JSON), with Access-Control-Allow-Origin: *, and never redirects. The message says where to copy a working URL. A token that is sent must be the right one, even next to a session or a key, so an old embed URL shows as old.
  • BOXARR_AUTH_WIDGET_TOKEN sets it by environment, and BOXARR_AUTH_WIDGETS sets the mode.

Under External, see the widgets through the proxy.

Environment variables

Every BOXARR_AUTH_* variable. Each one overrides auth.json, which overrides the default, and makes its field read-only in Settings → Security.

Variable What it does Default
BOXARR_AUTH_METHOD forms, external or none. none turns sign-in off and overrides everything else, a broken auth.json and invalid variables included Not set: auth.json decides. With neither, sign-in is off and the banner shows
BOXARR_AUTH_USERNAME The username for Forms, 1 to 64 characters Not set (the one in auth.json)
BOXARR_AUTH_PASSWORD_FILE Path to a file that holds the password. UTF-8, at most 4096 bytes; one trailing newline is dropped Not set
BOXARR_AUTH_PASSWORD The password in plain text (logs a warning) Not set
BOXARR_AUTH_PASSWORD_HASH A hash from --hash-password Not set
BOXARR_AUTH_API_KEY_FILE Path to a file that holds the API key (same file rules) Not set
BOXARR_AUTH_API_KEY The API key: 32 to 1024 printable ASCII characters, no spaces Not set (the one in auth.json)
BOXARR_AUTH_WIDGETS public or token public
BOXARR_AUTH_WIDGET_TOKEN The widget token: bxw_ and 16 to 128 letters, digits, - or _ Not set (Boxarr makes one)
BOXARR_AUTH_TRUSTED_PROXIES Your reverse proxy's addresses or networks, separated by commas or spaces. Replaces the list saved in Settings None trusted
BOXARR_AUTH_COOKIE_SECURE auto, always or never auto
BOXARR_AUTH_SESSION_HOURS How long a sign-in without "Keep me signed in" can last, 1 to 168 24
BOXARR_AUTH_REMEMBER_DAYS How long "Keep me signed in" can last, 0 to 90. 0 removes the option from the login page 90

Rules:

  • A blank variable counts as unset.
  • Set only one of the three password variables, and only one of the two API key variables.
  • An invalid value locks Boxarr, even while sign-in is off: everything but /api/health and static files answers 503, and the log names the variable (never its value). See Boxarr is locked.
  • A username, password or API key variable with no method anywhere also locks: set BOXARR_AUTH_METHOD=forms (or none).
  • When auth.json says none (after Keep it open, turning sign-in off, or --auth-reset) and BOXARR_AUTH_METHOD is not set, the username, password and API key variables are ignored. Boxarr logs an ERROR, and the banner says which variables are ignored. Set BOXARR_AUTH_METHOD=forms, or turn sign-in on in Settings.
  • An unknown BOXARR_AUTH_* variable is ignored with a warning.
  • Sign-in settings are never read from local.yaml. An auth key there is ignored with a warning.

Trusted proxies

BOXARR_AUTH_TRUSTED_PROXIES (or Trusted proxies in Settings, one per line) lists your reverse proxy's addresses. IPv4 and IPv6 addresses and CIDR networks are accepted, for example 172.20.0.5 or 172.20.0.0/24.

Sign-in believes X-Forwarded-For and X-Forwarded-Proto only from these addresses. They decide:

  • the address the throttle and the log see;
  • whether auto marks the cookie Secure;
  • under External, which connections get in.

Nothing is trusted by default, not even 127.0.0.1. FORWARDED_ALLOW_IPS plays no part in sign-in.

Entries Boxarr refuses:

  • *, 0.0.0.0/0, ::/0, an IPv4 network broader than /8 and an IPv6 network broader than /16 are never trusted. From the variable they are dropped with an ERROR; Settings refuses to save them.
  • An entry that is not an address or a network locks Boxarr when it comes from the variable. Settings refuses to save it.
  • An entry with an IPv6 zone, such as fe80::1%eth0, is refused too: no proxy needs one. From the variable it locks Boxarr, and in auth.json it makes the file invalid, which locks too. Settings answers Trusted proxies: entry 1 has a zone (%), which no proxy needs.
  • An IPv4 network broader than /24, or an IPv6 network broader than /64, is trusted with a warning. Trust only your proxy's own address.

Sessions and cookies

Sign-in Cookie Ends after inactivity Ends at the latest
Without "Keep me signed in" Until the browser closes 12 hours Sign-in lasts (hours): 24 by default, 1 to 168
With "Keep me signed in" Kept for the full length 30 days, renewed by use Keep me signed in (days): 90 by default, 0 to 90
  • The cookie is boxarr_<id>, or __Secure-boxarr_<id> when it is Secure. <id> is the instance id in auth.json, so two Boxarr instances on one host do not share a cookie. It is HttpOnly and SameSite=Lax, and its Path is the URL base (/boxarr/, or /).
  • Sessions survive a restart. Boxarr keeps at most 50; the least recently used goes first.
  • Requests the pages make in the background do not count as activity, so an open tab still signs out.
  • Sign out everywhere (Settings → Security → Sessions, Forms only) ends every sign-in on every browser and device. This one stays signed in.
  • A new username or password, turning sign-in off and switching between Forms and External also end every session.

Secure cookie (BOXARR_AUTH_COOKIE_SECURE):

  • auto (the default): Secure when the browser is on https. Boxarr knows that from the connection itself, or from the X-Forwarded-Proto of a trusted proxy. Behind a proxy that ends TLS but is not trusted, the cookie is not marked Secure.
  • always: always Secure. Use it only when Boxarr is reached over https alone. A browser on plain http drops a Secure cookie, so you could not stay signed in. Settings refuses to save always from a page on plain http.
  • never: never Secure.

Files

Boxarr keeps sign-in in two files, both written with mode 0600:

  • auth.json: the method, the username, the password's scrypt hash, the API key's SHA-256 and hint, the widget token, the trusted proxies and the cookie and session settings. The widget token is kept as it is, so Settings can show its embed URLs.
  • auth-sessions.json: the SHA-256 of each session token, with its times. Only Forms uses it.

They live in the directory named by BOXARR_DATA_DIRECTORY:

  • Docker: /config/auth.json and /config/auth-sessions.json.
  • Manual install without BOXARR_DATA_DIRECTORY: ./config/, relative to the directory Boxarr runs from. That differs from local.yaml, which such an install keeps in /config.

What Boxarr does with a bad file:

  • An auth.json it cannot read, or one that is not valid, locks Boxarr. A copy is kept as auth.json.broken (0600), and the log and the 503 page name the problem.
  • An auth.json that other users can read is set to 0600 at startup, with a warning.
  • A broken auth-sessions.json signs everyone out and is moved to .broken. It never locks Boxarr.

Back these files up with the rest of /config. Do not edit auth.json by hand: use Settings → Security, the variables or --auth-reset.

Hashing a password

--hash-password reads a password twice without showing it, and prints its hash for BOXARR_AUTH_PASSWORD_HASH:

# Docker (-it is needed for the prompt)
docker exec -it boxarr python -m src.main --hash-password

# Manual install
python -m src.main --hash-password

The output is one line in the form scrypt:14:8:2:<salt>:<key>. It has no $, so Docker Compose does not try to expand it. Boxarr hashes passwords with scrypt, N = 2^14, r = 8, p = 2 (16 MiB per check). The parameters travel with each hash, so a hash keeps working if they change.

Security notes

  • Sign-in protects every page and API route except GET /api/health, the static files, the login page with its sign-in and sign-out requests (Forms) and, while they are public, the two widgets.
  • The cross-site check from v2.1.2 still applies, to the login and logout requests too.
  • Boxarr logs no password, key, token or hash. The access log hides the values of apikey, api_key, token and password in URLs, and any bxk_ or bxw_ string.

Passwords from the environment

Under Forms, at startup, Boxarr compares a password from BOXARR_AUTH_PASSWORD_FILE, BOXARR_AUTH_PASSWORD or BOXARR_AUTH_PASSWORD_HASH with the one in auth.json:

  • The same password, moved into the environment: nothing changes, and no one is signed out. auth.json now records the password as the environment's, so a later change there counts as your own (next item). With BOXARR_AUTH_PASSWORD_HASH, this holds only for the exact hash auth.json holds. A hash from --hash-password has a new salt, so it counts as a new password, and replacing one set in Settings starts over. To move a password set in Settings into the environment unchanged, use BOXARR_AUTH_PASSWORD_FILE, or copy the password_hash value from auth.json as it is.

  • A new password, and the old one came from the environment (you change it there): it is stored and every session is signed out. Everything else is kept.

  • A new password, and the old one was set in Settings → Security: auth.json starts over. The API key, the widget token, the trusted proxies and every setting saved there are cleared; only the instance id, the username and the new password are kept. Every session is signed out. The username is the one in auth.json unless BOXARR_AUTH_USERNAME sets it. A WARNING names what was cleared and who to sign in as:

    Authentication: the password from BOXARR_AUTH_PASSWORD_FILE replaces the one set in Settings → Security, so /config/auth.json started over: the API key, the trusted proxies and every setting saved there were cleared. Sign in as admin (set BOXARR_AUTH_USERNAME to choose another username); create a new API key in Settings → Security if you use one.
    

    The part in brackets is left out when BOXARR_AUTH_USERNAME is set. If auth.json cannot be written, Boxarr locks until it can, rather than keep the old settings next to your password.

  • No password in auth.json yet (sign-in came from the environment alone, or after Keep it open or --auth-reset): the password is stored, and what you saved in Settings under BOXARR_AUTH_METHOD, such as an API key, is kept. Settings turns sign-in on only with a password, so no one else can have left a sign-in without one.

When nothing has to start over, a file that cannot be written only logs a warning: the password from the environment applies until Boxarr restarts.

Under External, a password variable is never stored, and nothing starts over: see A password variable under External.

If someone else reached Boxarr first

Sign-in is off after an upgrade. While it is off, after Keep it open too, anyone who can reach Boxarr can turn sign-in on with their own password, make an API key, or switch the widgets to their own token. These behaviours stop such a person from keeping access once you take Boxarr back:

  1. Turning sign-in off erases it. The username, password, API key, widget token and every setting are cleared, and every session ends. auth.json keeps only its instance id and credential generation.
  2. Every first enable starts over. Turning sign-in on from Off keeps nothing from before and issues a new API key, unless a variable sets the key.
  3. A save under BOXARR_AUTH_METHOD=none starts over when it stores new credentials, Forms over a stored Off or External, or Off. The API key, widget token, trusted proxies and other settings stored before are removed.
  4. A password from the environment that replaces one set in Settings (Forms) clears the API key, the widget token, the trusted proxies and every setting saved there. If auth.json cannot be written, Boxarr locks instead. The same password moved into the environment keeps everything, and so does changing a password the environment set. See Passwords from the environment.
  5. External with no password set: anyone the proxy lets in can change the Security settings. Set a password when your proxy admits more than one user.

While sign-in is off, the settings that would weaken a later sign-in (trusted proxies, the Secure cookie, the session lengths and the widgets mode) can be saved only along with turning sign-in on. External cannot be chosen while sign-in is off.

Under External, a sign-in set up earlier in Settings is kept. With a sign-in variable set too, every start logs a WARNING: see External over a sign-in set up in Settings.

If you did not set up the sign-in you find, or are not sure, run --auth-reset and set it up again.

Recovery

Forgot the password

Use one of these. Each signs everyone out.

1. A new password from the environment (Forms). Set BOXARR_AUTH_PASSWORD_FILE (or BOXARR_AUTH_PASSWORD, or BOXARR_AUTH_PASSWORD_HASH) and restart Boxarr. Add BOXARR_AUTH_USERNAME if you forgot the username too, and BOXARR_AUTH_METHOD=forms unless auth.json already says forms. If the old password was set in Settings → Security, the API key, the widget token, the trusted proxies and every other setting saved there are cleared (why), and the log names the username to sign in with: create a new API key afterwards. The new password is stored, so you can remove the variable later.

2. --auth-reset. See below. It clears everything, so you set sign-in up again from the start.

3. BOXARR_AUTH_METHOD=none. Set it and restart. Sign-in is off while it is set: anyone who can reach Boxarr can use it. Settings → Security asks for no password then, and what you save goes to auth.json and applies once you remove the variable:

  1. Choose On, enter a username and a new password, and save. This starts auth.json over: the API key, the widget token, the trusted proxies and the other settings stored before are removed, and no API key is made.
  2. Remove BOXARR_AUTH_METHOD=none and restart Boxarr.
  3. Sign in, and create a new API key in Settings → Security if you use one.

External cannot be saved under BOXARR_AUTH_METHOD=none. Choose On or Off, and switch to External again once you are signed in.

Under External, the password only confirms changes in Settings → Security. If you forgot it:

  • Set a password variable (BOXARR_AUTH_PASSWORD_FILE, BOXARR_AUTH_PASSWORD or BOXARR_AUTH_PASSWORD_HASH) and restart Boxarr. It confirms changes in place of the stored one while it is set. It is never stored under External, and the old password stays in auth.json.
  • Or run --auth-reset to clear it. What follows depends on where External came from:
    • External chosen in Settings: after the restart sign-in is off. Turn Forms on again, then switch to External (how).
    • External set by BOXARR_AUTH_METHOD=external: keep the variable and make sure BOXARR_AUTH_TRUSTED_PROXIES is set. After the restart External applies with no password: set a new one in Settings → Security through your proxy.

Reset sign-in with --auth-reset

--auth-reset turns sign-in off without starting the server. It works even when local.yaml is broken.

# Docker
docker exec boxarr python -m src.main --auth-reset

# Manual install: from the directory Boxarr runs from, with the same BOXARR_DATA_DIRECTORY
python -m src.main --auth-reset

It writes auth.json with method none and clears the username, the password, the API key, the widget token, the trusted proxies and every setting. Only the instance id is kept, with a new credential generation. It signs out every session. The output:

Authentication is off: /config/auth.json now says method none, and its username, password, API key and settings were cleared; every session was signed out.
Restart Boxarr to apply it, then set sign-in up again in Settings → Security.

Then:

  1. Check BOXARR_AUTH_METHOD. It overrides auth.json, and the command says so:
    • forms or external: BOXARR_AUTH_METHOD=external is set in this environment and overrides auth.json: after the restart, sign-in is external, with what the environment sets. Remove it only if you want sign-in off. Keep it to keep sign-in on. Under forms, the environment must then set the username and a password too, or Boxarr locks. Under external, set BOXARR_AUTH_TRUSTED_PROXIES, since the reset cleared the saved list.
    • Any other value but none: BOXARR_AUTH_METHOD is set in this environment and overrides auth.json: fix or remove it before the restart.
    • none, or not set: the command says nothing more, and sign-in is off after the restart.
  2. Restart Boxarr. A running Boxarr does not see the change until then.
  3. If sign-in is off, set it up again in Settings → Security. Turning it on makes a new API key, unless a variable sets one. If you kept BOXARR_AUTH_METHOD, sign-in is already on: create a new API key in Settings → Security if you use one.

Boxarr is locked

When the sign-in settings are invalid, Boxarr answers only /api/health and its static files, and every other request gets a 503 that names the problem. See Troubleshooting.


← Configuration Guide | Home | Troubleshooting →

Clone this wiki locally