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/widget
The app moves a user:pass credential from the URL into a header
before it sends the request. URLs appear in caches, logs and error messages. A header does
not. A scheme that you set on the hook overrides a credential 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 app applies
- The app never sends a credential over plain HTTP. This is also true when the HTTPS check is off for local development.
- The app removes the credential header on a redirect to a different host. A redirect to the same host keeps it.
- A password never appears in a cache filename, an error message or the app.
The app makes cache keys from the URL without its credential. Where the app shows a URL,
it replaces the credential with
•••. - The app checks for HTTPS at every redirect, and on the first request.
Where credentials are stored
The app stores a hook's URL and credential together, in the container that the app and the widget share. The widget on the Home Screen holds only the hook's name. The credential is not in WidgetKit's configuration store.