Protocol
Authentication
The widget sends the same token or password with every request. Use the format your server already supports. You can configure the last three options in the app.
| Scheme | How to configure | What is sent |
|---|---|---|
| Query token | Write it into the URL: ?key=s3cret | Your parameter, preserved exactly |
| Basic, no UI | https://user:pass@host/feed | Authorization: Basic … |
| Basic | Hook → Authentication → Basic | Authorization: Basic … |
| Bearer | Hook → Authentication → Bearer token | Authorization: Bearer … |
| Custom header | Hook → Authentication → Custom header | e.g. X-API-Key: … |
Zero-configuration forms
https://you.example/widget?key=s3cret
# Or with credentials in the URL, which are moved into a header before the
# request leaves the device:
https://user:pass@you.example/widgetCredentials written into a URL are moved into a header before the request goes out. Userinfo in a URL is too widely mishandled to leave in place — it ends up in caches, logs and error messages. An explicitly configured scheme overrides anything embedded in the URL.
Verifying on your side
app.get("/widget", (request, response) => {
const token = request.headers.authorization?.replace(/^Bearer /, "");
if (token !== process.env.WIDGET_TOKEN) {
return response.status(401).json({ error: "unauthorized" });
}
response.json({ view: buildView(request.query) });
});Rules the client enforces
- Credentials are never sent over plain HTTP, even with the HTTPS check disabled for local development. That opt-out exists for convenience; leaking a password does not.
- A redirect to a different host drops the credential header. A server cannot bounce the widget somewhere else to harvest a token it was given. Same-host redirects keep it.
- Passwords never reach a cache filename, an error message or the app's UI.
Cache keys hash the credential-free URL, and anywhere a URL is displayed it is redacted
to
•••. - HTTPS is re-checked at every redirect hop, not just on the first request.
Where credentials are stored
A hook's URL and credential are stored together in the app, in the container the app and the widget share. The widget on the Home Screen holds only the hook's name, so a secret never reaches WidgetKit's configuration store.