Repository navigation
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.
- 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-passwordand--auth-reset. -
Health: while sign-in is on, an anonymous
GET /api/healthanswers 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 readsradarr_connectedneeds the API key. A monitor that probes/should probe/api/health, which needs no sign-in.
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.
| 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.
- Open Settings (
/setup) and scroll to Security, or click Set up login on the banner. - Set Sign-in to On: sign in with a username and password.
- Enter a Username, a Password and Repeat the password.
- 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).
- 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.
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.txtFor 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, becausedocker inspectshows 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 saysAuthentication: 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.jsonstarts over and every setting saved there is cleared. The same password moved into the environment changes nothing. See Passwords from the environment.
- 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 inBOXARR_AUTH_TRUSTED_PROXIES.
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,ForwardedandRemote-Usercan 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.
- Turn Forms on first, and sign in through your proxy.
- 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). - 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.
environment:
- BOXARR_URL_BASE=boxarr
- BOXARR_AUTH_METHOD=external
- BOXARR_AUTH_TRUSTED_PROXIES=172.20.0.5 # the proxy's address, as Boxarr sees itA 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;
}-
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_PASSWORDorBOXARR_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 inauth.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 aloneSecurity 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).
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.
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 withbxk_counts here).
-
- Never in the URL.
?apikey=and?api_key=are ignored, and the 401 saysAn 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/currentWhat it opens:
- API requests:
GETon/api/...and/openapi.json, and anyPOST,PUTorDELETE. - 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 403API 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>.
/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 examplehttps://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_TOKENsets it by environment, andBOXARR_AUTH_WIDGETSsets the mode.
Under External, see the widgets through the proxy.
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/healthand 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(ornone). - When
auth.jsonsaysnone(after Keep it open, turning sign-in off, or--auth-reset) andBOXARR_AUTH_METHODis not set, the username, password and API key variables are ignored. Boxarr logs an ERROR, and the banner says which variables are ignored. SetBOXARR_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. Anauthkey there is ignored with a warning.
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
automarks 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/8and an IPv6 network broader than/16are 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 inauth.jsonit makes the file invalid, which locks too. Settings answersTrusted 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.
| 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 inauth.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 theX-Forwarded-Protoof 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 savealwaysfrom a page on plain http. -
never: never Secure.
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.jsonand/config/auth-sessions.json. - Manual install without
BOXARR_DATA_DIRECTORY:./config/, relative to the directory Boxarr runs from. That differs fromlocal.yaml, which such an install keeps in/config.
What Boxarr does with a bad file:
- An
auth.jsonit cannot read, or one that is not valid, locks Boxarr. A copy is kept asauth.json.broken(0600), and the log and the 503 page name the problem. - An
auth.jsonthat other users can read is set to 0600 at startup, with a warning. - A broken
auth-sessions.jsonsigns 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.
--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-passwordThe 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.
- 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,tokenandpasswordin URLs, and anybxk_orbxw_string.
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.jsonnow records the password as the environment's, so a later change there counts as your own (next item). WithBOXARR_AUTH_PASSWORD_HASH, this holds only for the exact hashauth.jsonholds. A hash from--hash-passwordhas 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, useBOXARR_AUTH_PASSWORD_FILE, or copy thepassword_hashvalue fromauth.jsonas 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.jsonstarts 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 inauth.jsonunlessBOXARR_AUTH_USERNAMEsets 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_USERNAMEis set. Ifauth.jsoncannot be written, Boxarr locks until it can, rather than keep the old settings next to your password. -
No password in
auth.jsonyet (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 underBOXARR_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.
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:
-
Turning sign-in off erases it. The username, password, API key, widget token and every setting are cleared, and every session ends.
auth.jsonkeeps only its instance id and credential generation. - 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.
-
A save under
BOXARR_AUTH_METHOD=nonestarts 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. -
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.jsoncannot 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. - 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.
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:
- Choose On, enter a username and a new password, and save. This starts
auth.jsonover: the API key, the widget token, the trusted proxies and the other settings stored before are removed, and no API key is made. - Remove
BOXARR_AUTH_METHOD=noneand restart Boxarr. - 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_PASSWORDorBOXARR_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 inauth.json. - Or run
--auth-resetto 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 sureBOXARR_AUTH_TRUSTED_PROXIESis set. After the restart External applies with no password: set a new one in Settings → Security through your proxy.
--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-resetIt 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:
- Check
BOXARR_AUTH_METHOD. It overridesauth.json, and the command says so:-
formsorexternal: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. Underforms, the environment must then set the username and a password too, or Boxarr locks. Underexternal, setBOXARR_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.
-
- Restart Boxarr. A running Boxarr does not see the change until then.
- 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.
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.