Access control
Without a rule, anyone on your wifi could spend your model credits and delete your boards. The rule here is deliberately small.
{ width="640" }
The rule
- Requests from the server itself (loopback) are always allowed. Opening
https://localhost:8443/on the server needs nothing. - Every other client needs the access token, in one of the three ways below.
- 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 token | Used by |
|---|---|
The cookie set by /login | Browsers |
Authorization: Bearer <token> | Scripts |
?token=<token> once in any URL | The 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:
--tokenon the command line.- The
SOLDERMASK_TOKENenvironment variable. access-tokenin the cache directory, generated on first start and reused after. In a checkout that is.cache/access-token.soldermask setup --checkprints 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-ProtoandX-Forwarded-Hostare 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.