43 lines
2.3 KiB
Plaintext
43 lines
2.3 KiB
Plaintext
# Configure requests and security
|
|
|
|
Most widgets use a single source named `default`. Extra keyed sources are available under Advanced for widgets that combine APIs. Authentication is `none`, `bearer`, `basic`, an API-key header, or an API-key query parameter. Credentials belong to the widget but remain outside its manifest.
|
|
|
|
## Named requests
|
|
|
|
Requests are keyed by ID. `source`, `kind`, `method`, `trigger`, `auth`, and `permission` have sensible defaults, so a load query can be as small as:
|
|
|
|
```json
|
|
{ "status": { "path": "/api/status" } }
|
|
```
|
|
|
|
The request `path` is appended to the source `baseUrl`, including a base path such as `/api/v2`.
|
|
|
|
GET, POST, PUT, PATCH, and DELETE work for queries and actions. Kind—not method—controls behavior. Load queries run automatically, manual queries run through `SubFetch`, and actions run only from `ActionButton` or `ToggleSwitch`.
|
|
|
|
Bind values directly where they are used:
|
|
|
|
```json
|
|
{
|
|
"containers": {
|
|
"path": "/api/endpoints/{option:endpointId}/docker/containers/json",
|
|
"query": { "all": { "$option": "showAll" } }
|
|
},
|
|
"restart": {
|
|
"kind": "action",
|
|
"method": "POST",
|
|
"path": "/api/endpoints/{option:endpointId}/docker/containers/{param:id}/restart",
|
|
"invalidates": ["containers"]
|
|
}
|
|
}
|
|
```
|
|
|
|
`{option:name}` and `$option` read saved widget options. `{param:name}` and `$param` read invocation-time `params`. Load queries cannot use invocation parameters. Homarr infers the exact parameter names and primitive values from these references, rejecting missing or extra invocation params at the request boundary.
|
|
|
|
Paths and query-string values must resolve to text, numbers, or booleans. JSON bodies can also use structured `json` and `multiSelect` option values, for example `{ "entity_ids": { "$option": "entities" } }`.
|
|
|
|
## Protection
|
|
|
|
Every request uses Homarr's existing server executor: same-origin source enforcement, network scope, DNS and redirect validation, SSRF protection, board permissions, rate and request limits, body and response limits, timeouts, and encrypted credential injection. Static headers cannot override credentials, cookies, routing, proxy, forwarding, or hop-by-hop headers.
|
|
|
|
Queries default to view permission and actions to modify. DELETE always requires full permission and confirmation. Actions are never cached, retried, or run on load.
|