This is an automated email from the ASF dual-hosted git repository.
rusackas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git
The following commit(s) were added to refs/heads/master by this push:
new b8995561300 docs: Superset 6.1 documentation catch-up (security,
alerts/reports, theming, config) (#39440)
b8995561300 is described below
commit b8995561300cd9854a65fee558e54e792bb1899d
Author: Evan Rusackas <[email protected]>
AuthorDate: Fri May 8 10:11:09 2026 -0700
docs: Superset 6.1 documentation catch-up (security, alerts/reports,
theming, config) (#39440)
Co-authored-by: Superset Dev <[email protected]>
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
---
docs/admin_docs/configuration/alerts-reports.mdx | 81 ++++++++++++++++++++++
.../configuration/configuring-superset.mdx | 32 +++++++++
docs/admin_docs/configuration/theming.mdx | 17 ++++-
docs/admin_docs/security/security.mdx | 51 ++++++++++++++
4 files changed, 180 insertions(+), 1 deletion(-)
diff --git a/docs/admin_docs/configuration/alerts-reports.mdx
b/docs/admin_docs/configuration/alerts-reports.mdx
index b66f641e290..f5c4efc42ed 100644
--- a/docs/admin_docs/configuration/alerts-reports.mdx
+++ b/docs/admin_docs/configuration/alerts-reports.mdx
@@ -81,6 +81,87 @@ SLACK_CACHE_TIMEOUT = int(timedelta(days=2).total_seconds())
SLACK_API_RATE_LIMIT_RETRY_COUNT = 5
```
+### Webhook integration
+
+Superset can send alert and report notifications to any HTTP endpoint — useful
for chat platforms, incident management tools, or custom automation.
+
+#### Enabling Webhooks
+
+Enable the feature flag in `superset_config.py`:
+
+```python
+FEATURE_FLAGS = {
+ "ALERT_REPORTS": True,
+ "ALERT_REPORT_WEBHOOK": True,
+}
+```
+
+#### Configuring a Webhook Recipient
+
+When creating or editing an alert or report, select **Webhook** as the
notification method and enter your endpoint URL.
+
+#### Payload Format
+
+Superset sends an HTTP POST with `Content-Type: application/json`:
+
+```json
+{
+ "name": "My Alert",
+ "header": {
+ "notification_format": "JSON",
+ "notification_type": "Alert",
+ "notification_source": "Alert",
+ "chart_id": 42,
+ "dashboard_id": null
+ },
+ "text": "Alert condition met: value exceeded threshold",
+ "description": "Monthly revenue dropped below target",
+ "url": "https://your-superset-host/superset/dashboard/1/";
+}
+```
+
+When a report includes file attachments (CSV, PDF, or PNG screenshots), the
request is sent as `multipart/form-data` instead. In that case, each top-level
payload field (`name`, `text`, `description`, `url`) becomes its own form
field, and nested structures like `header` are serialized as a JSON-encoded
string in their own field. Every attachment is added as a repeated form field
named `files`:
+
+```
+POST /webhook HTTP/1.1
+Content-Type: multipart/form-data; boundary=...
+
+--...
+Content-Disposition: form-data; name="name"
+
+My Alert
+--...
+Content-Disposition: form-data; name="header"
+
+{"notification_format": "JSON", "notification_type": "Alert", ...}
+--...
+Content-Disposition: form-data; name="text"
+
+Alert condition met: value exceeded threshold
+--...
+Content-Disposition: form-data; name="files"; filename="report.csv"
+Content-Type: text/csv
+
+<file bytes>
+--...
+```
+
+Webhook consumers should branch on `Content-Type`: parse the body as JSON when
`application/json`, or read the individual form fields (decoding `header` as
JSON) when `multipart/form-data`.
+
+#### HTTPS Enforcement
+
+To require HTTPS webhook URLs (recommended for production), set:
+
+```python
+ALERT_REPORTS_WEBHOOK_HTTPS_ONLY = True
+```
+
+When enabled, Superset rejects webhook configurations that use `http://` URLs.
+
+#### Retry Behavior
+
+Superset automatically retries webhook deliveries on `429 Too Many Requests`
and `5xx` server errors using exponential backoff.
+
### Kubernetes-specific
- You must have a `celery beat` pod running. If you're using the chart
included in the GitHub repository under
[helm/superset](https://github.com/apache/superset/tree/master/helm/superset),
you need to put `supersetCeleryBeat.enabled = true` in your values override.
diff --git a/docs/admin_docs/configuration/configuring-superset.mdx
b/docs/admin_docs/configuration/configuring-superset.mdx
index becdf70888b..daf92b1c943 100644
--- a/docs/admin_docs/configuration/configuring-superset.mdx
+++ b/docs/admin_docs/configuration/configuring-superset.mdx
@@ -472,6 +472,38 @@ FEATURE_FLAGS = {
A current list of feature flags can be found in the [Feature
Flags](/admin-docs/configuration/feature-flags) documentation.
+## Security Configuration
+
+### HASH_ALGORITHM
+
+Controls the hashing algorithm used for internal checksums and cache keys
(thumbnails, cache keys, etc.). The default is `sha256`, which satisfies
environments with stricter compliance requirements (e.g., FedRAMP). Set it to
`md5` to retain the legacy behavior from older Superset deployments:
+
+```python
+HASH_ALGORITHM = "sha256" # default; set to "md5" for legacy behavior
+```
+
+A companion `HASH_ALGORITHM_FALLBACKS` list (default: `["md5"]`) lets UUID
lookups fall back to older algorithms, which enables gradual migration without
breaking existing entries. Set it to `[]` for strict mode (use only
`HASH_ALGORITHM`).
+
+:::note
+This setting affects internal Superset operations only, not user passwords or
authentication tokens. Changing it in an existing deployment may invalidate
cached values but does not require a database migration.
+:::
+
+## SQL Lab Query History Pruning
+
+SQL Lab query history is stored in the metadata database and is **not** pruned
by default. To trim older rows, enable the `prune_query` Celery beat task by
uncommenting it in `CELERY_BEAT_SCHEDULE` and choosing a retention window:
+
+```python
+CELERY_BEAT_SCHEDULE = {
+ "prune_query": {
+ "task": "prune_query",
+ "schedule": crontab(minute=0, hour=0, day_of_month=1),
+ "kwargs": {"retention_period_days": 180},
+ },
+}
+```
+
+Adjust `retention_period_days` to control how long query rows are kept.
Companion opt-in tasks (`prune_logs`, `prune_tasks`) exist for pruning the logs
and tasks tables; see the commented-out examples in `superset/config.py`.
Without enabling these tasks, the metadata database will grow unbounded over
time.
+
:::resources
- [Blog: Feature Flags in Apache
Superset](https://preset.io/blog/feature-flags-in-apache-superset-and-preset/)
:::
diff --git a/docs/admin_docs/configuration/theming.mdx
b/docs/admin_docs/configuration/theming.mdx
index c13e42617a0..92e4fcd8e59 100644
--- a/docs/admin_docs/configuration/theming.mdx
+++ b/docs/admin_docs/configuration/theming.mdx
@@ -122,6 +122,17 @@ When `ENABLE_UI_THEME_ADMINISTRATION = True`:
3. Administrators can change system themes without restarting Superset
4. Configuration file themes serve as fallbacks when no UI themes are set
+### Theme Validation and Fallback
+
+Superset validates theme JSON when it is saved, either through the UI or via
configuration. If a theme contains invalid tokens or an unrecognized structure,
Superset logs a warning and falls back to the built-in default theme rather
than applying a broken configuration. This prevents a bad theme from rendering
the application unusable.
+
+The fallback order is:
+1. **UI-configured system theme** (highest priority, if
`ENABLE_UI_THEME_ADMINISTRATION = True`)
+2. **`THEME_DEFAULT` / `THEME_DARK`** from `superset_config.py`
+3. **Built-in Superset default theme** (always present as a safety net)
+
+If you see unexpected styling after a config change, check the Superset server
logs for theme validation warnings.
+
### Copying Themes Between Systems
To export a theme for use in configuration files or another instance:
@@ -143,7 +154,11 @@ Superset supports custom fonts through the theme
configuration, allowing you to
### Default Fonts
-By default, Superset uses Inter and Fira Code fonts which are bundled with the
application via `@fontsource` packages. These fonts work offline and require no
external network calls.
+By default, Superset uses **Inter** for UI text and **IBM Plex Mono** for code
(SQL editors, JSON fields, and other monospace contexts). Both fonts are
bundled with the application via `@fontsource` packages and work offline
without any external network calls.
+
+:::note
+IBM Plex Mono replaced Fira Code as the default code font in Superset 6.1. If
you have an existing theme that explicitly sets `fontFamilyCode: "Fira Code,
..."`, you may want to update it.
+:::
### Configuring Custom Fonts
diff --git a/docs/admin_docs/security/security.mdx
b/docs/admin_docs/security/security.mdx
index b4261c60bf5..6190925d8ab 100644
--- a/docs/admin_docs/security/security.mdx
+++ b/docs/admin_docs/security/security.mdx
@@ -205,6 +205,57 @@ FAB_ADD_SECURITY_API = True
Once configured, the documentation for additional "Security" endpoints will be
visible in Swagger for you to explore.
+### API Key Authentication
+
+Superset supports long-lived API keys for service accounts, CI/CD pipelines,
and programmatic integrations (including MCP clients).
+
+#### Enabling API Key Authentication
+
+API key authentication is **disabled by default**. To turn it on, set the
Flask-AppBuilder config value in `superset_config.py` and also enable the
matching feature flag so the management UI is exposed:
+
+```python
+FAB_API_KEY_ENABLED = True
+
+FEATURE_FLAGS = {
+ "FAB_API_KEY_ENABLED": True,
+}
+```
+
+The config value registers the `ApiKeyApi` blueprint on the backend; the
feature flag controls whether the UI for managing keys appears for the user.
See the [Feature Flags](/admin-docs/configuration/feature-flags) documentation
for more on feature flag configuration.
+
+#### Creating an API Key
+
+Once enabled, each user manages their own keys from their profile page:
+
+1. Open the user menu (top-right) and click **Info** to navigate to the User
Info page
+2. Expand the **API Keys** section
+3. Click **+ API Key**
+4. Enter a name and (optionally) an expiration date
+5. Copy the generated token — it is shown only once
+
+Only users with the `can_read` and `can_write` permissions on `ApiKey`
(granted by default to Admins) can manage API keys.
+
+#### Using an API Key
+
+Pass the key as a Bearer token in the `Authorization` header:
+
+```
+Authorization: Bearer <your-api-key>
+```
+
+This works for all REST API endpoints and the MCP server. The request is
executed with the permissions of the user who created the key.
+
+#### Use Cases
+
+- **CI/CD pipelines** — automated chart/dashboard exports and imports
+- **MCP integrations** — connect AI assistants without interactive login
+- **External services** — dashboards embedded in other applications
+- **Service accounts** — long-lived credentials that don't expire with session
cookies
+
+:::caution
+Store API keys securely. Anyone with a valid key can make requests on behalf
of the creating user. Revoke keys promptly if they are compromised by deleting
them from the **API Keys** section of your User Info page.
+:::
+
### Customizing Permissions
The permissions exposed by FAB are very granular and allow for a great level of
