soldermaskdocs

Access control

Without a rule, anyone on your wifi could spend your model credits and delete your boards. The rule here is deliberately small.

The login page other devices see{ width="640" }

The rule

  1. Requests from the server itself (loopback) are always allowed. Opening https://localhost:8443/ on the server needs nothing.
  2. Every other client needs the access token, in one of the three ways below.
  3. Five wrong tokens from one address within a minute lock that address out for up to a minute, even with the right token.
Way to present the tokenUsed by
The cookie set by /loginBrowsers
Authorization: Bearer <token>Scripts
?token=<token> once in any URLThe QR code printed at startup. It is swapped for the cookie and removed from the address bar.

The cookie is HttpOnly, SameSite=Lax and Secure on TLS, and lasts thirty days. It holds a value derived from the token, never the token itself. POST /logout clears it.

Where the token comes from

The server takes the first of these that is set:

  1. --token on the command line.
  2. The SOLDERMASK_TOKEN environment variable.
  3. access-token in the cache directory, generated on first start and reused after. In a checkout that is .cache/access-token. soldermask setup --check prints where the cache is.

The generated token is 24 random characters, stored with file mode 0600. Because it is reused, the QR code stays valid across restarts. It is printed at startup:

  access token : ExampleToken-NotYours-24   (other devices; this machine needs none)

Turning access control off

--no-auth, or SOLDERMASK_TOKEN=off, opens the app to everyone on the network. The startup banner then says access: OPEN.

Behind a proxy

Behind a reverse proxy, every request arrives from loopback, so the local exemption would let everyone in. Run with --proxy:

  • X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host are trusted.
  • The token is required from every client, loopback included.

See Deploying.

What is always open

These paths need no token: /api/health, /static/*, /manifest.webmanifest, /login and /logout. Everything else, including pages, the API and the docs, follows the rule.

On this page