From bfc1d3f2d9296feb5f5880becde3411ae30b62fc Mon Sep 17 00:00:00 2001 From: Herbert Wolverson Date: Fri, 17 Jul 2026 10:04:01 -0500 Subject: [PATCH] Document named local API keys --- docs-es/v2.0/api-es.md | 6 ++++-- docs-es/v2.0/insight-es.md | 2 +- docs-es/v2.0/troubleshooting-es.md | 2 +- docs-es/v2.0/update-es.md | 2 +- docs/v2.0/api.md | 6 ++++-- docs/v2.0/insight.md | 2 +- docs/v2.0/troubleshooting.md | 2 +- docs/v2.0/update.md | 2 +- 8 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs-es/v2.0/api-es.md b/docs-es/v2.0/api-es.md index 6da5ddd8..c5f6456e 100644 --- a/docs-es/v2.0/api-es.md +++ b/docs-es/v2.0/api-es.md @@ -64,9 +64,11 @@ sudo systemctl status lqos_api La mayoría de endpoints requieren: - Header: `x-bearer` -- Valor: el token Bearer de la API local configurado en **License & Services**, o su clave de licencia Insight/API-only +- Valor: una clave local con nombre creada en **License & Services**, el token local heredado o su clave de licencia Insight/API-only -El token local autentica al cliente, pero no evita el límite de licenciamiento por circuitos mapeados. Genere un token de 256 bits en **License & Services**, cópielo a su cliente de API antes de guardar y trátelo como una contraseña. Los tokens guardados no vuelven a mostrarse; genere uno nuevo si pierde el original. +Las claves locales autentican al cliente, pero no evitan el límite de licenciamiento por circuitos mapeados. Un administrador puede crear hasta 16 claves con nombre en **License & Services**. LibreQoS muestra cada clave una sola vez, guarda únicamente su resumen SHA-256 y metadatos no secretos en `/etc/lqos.conf`, y no puede recuperarla después. Copie de inmediato el valor completo `lqos_api_...` al cliente y trátelo como una contraseña. + +Las claves con nombre no caducan automáticamente. Revoque las que ya no necesite; la creación y la revocación pueden tardar hasta 30 segundos en surtir efecto en `lqos_api`. Las claves de licencia existentes y el antiguo `local_api.bearer_token` siguen siendo compatibles. La interfaz identifica este último como **Legacy local API key** y permite eliminarlo después de migrar los clientes. ## Qué pueden hacer los ISPs con la API diff --git a/docs-es/v2.0/insight-es.md b/docs-es/v2.0/insight-es.md index 08c18b02..334452d3 100644 --- a/docs-es/v2.0/insight-es.md +++ b/docs-es/v2.0/insight-es.md @@ -130,7 +130,7 @@ Sin un estado válido de licencia/grant de Insight o Local, LibreQoS admite solo Un estado válido de licencia/grant con derecho habilita conteos de circuitos mapeados por encima del límite predeterminado de 1000. -A partir de LibreQoS 2.2, la API del nodo usa este mismo conteo de circuitos mapeados válidos únicos. El acceso a la API está disponible sin una suscripción a Insight para 1.000 circuitos mapeados o menos. Por encima de 1.000, la API requiere un derecho activo válido o un grant firmado almacenado localmente. Los clientes todavía deben autenticarse con un token Bearer de la API local o una clave de licencia Insight/API-only. +A partir de LibreQoS 2.2, la API del nodo usa este mismo conteo de circuitos mapeados válidos únicos. El acceso a la API está disponible sin una suscripción a Insight para 1.000 circuitos mapeados o menos. Por encima de 1.000, la API requiere un derecho activo válido o un grant firmado almacenado localmente. Los clientes todavía deben autenticarse con una clave local con nombre, el token local heredado o una clave de licencia Insight/API-only. Los administradores crean y revocan las claves con nombre en **License & Services**; los cambios pueden tardar hasta 30 segundos en surtir efecto en `lqos_api`. El comportamiento predeterminado del límite de 1000 aplica cuando el estado de licencia/grant está: - ausente diff --git a/docs-es/v2.0/troubleshooting-es.md b/docs-es/v2.0/troubleshooting-es.md index 11ca3f28..787a77b3 100644 --- a/docs-es/v2.0/troubleshooting-es.md +++ b/docs-es/v2.0/troubleshooting-es.md @@ -271,7 +271,7 @@ Checks recomendados: 2. Revisar logs de `lqosd` para requested/allowed/dropped. 3. Reducir circuitos mapeados (corto plazo) o ajustar licencia/límites (largo plazo). -La API del nodo usa el mismo conteo a partir de LibreQoS 2.2. Con 1.000 circuitos mapeados o menos, confirme que haya un token Bearer de la API local configurado y que `lqos_api` esté en ejecución. Por encima de 1.000, confirme además que el derecho efectivo de API o Insight sea válido. +La API del nodo usa el mismo conteo a partir de LibreQoS 2.2. Con 1.000 circuitos mapeados o menos, confirme que haya una clave local con nombre (o una clave heredada/de licencia compatible) y que `lqos_api` esté en ejecución. Una clave nueva o revocada puede tardar hasta 30 segundos en surtir efecto. Por encima de 1.000, confirme además que el derecho efectivo de API o Insight sea válido. ### Códigos de problemas urgentes y primeras acciones diff --git a/docs-es/v2.0/update-es.md b/docs-es/v2.0/update-es.md index ffc4fdd7..802d8c3e 100644 --- a/docs-es/v2.0/update-es.md +++ b/docs-es/v2.0/update-es.md @@ -9,7 +9,7 @@ Si usas el puente XDP, el tráfico dejará de pasar por el puente mientras lqosd ```{important} Desde v2.0, la ingesta de circuitos mapeados depende de un estado válido de licencia/grant con derecho. Sin un estado válido de licencia/grant de Insight o Local, LibreQoS solo lee los primeros 1000 circuitos mapeados válidos al estado de shaping activo. Esto incluye estado local de grant/licencia expirado o inválido por cualquier motivo. Vea [Comportamiento de licenciamiento de Insight](insight-es.md#límites-de-circuitos-mapeados-y-estado-de-licencia) y [Solución de problemas](troubleshooting-es.md). -A partir de v2.2, la API del nodo usa la misma política. Las redes con 1.000 circuitos mapeados válidos o menos pueden usar la API sin una suscripción a Insight; las redes mayores requieren un derecho válido de API o Insight. Las llamadas continúan autenticadas con un token Bearer de la API local o una clave de licencia existente. +A partir de v2.2, la API del nodo usa la misma política. Las redes con 1.000 circuitos mapeados válidos o menos pueden usar la API sin una suscripción a Insight; las redes mayores requieren un derecho válido de API o Insight. Las llamadas continúan autenticadas. Un administrador puede crear hasta 16 claves locales con nombre en **License & Services**; cada clave se muestra una sola vez, se guarda únicamente como resumen SHA-256 y se puede revocar. Las claves de licencia y el token local heredado siguen siendo compatibles, y los cambios pueden tardar hasta 30 segundos en surtir efecto. ``` Ejecuta: diff --git a/docs/v2.0/api.md b/docs/v2.0/api.md index 13e82899..99fb0e58 100644 --- a/docs/v2.0/api.md +++ b/docs/v2.0/api.md @@ -64,9 +64,11 @@ sudo systemctl status lqos_api Most endpoints require: - Header: `x-bearer` -- Value: either the local API bearer token configured under **License & Services**, or your Insight/API-only license key +- Value: a named local API key from **License & Services**, the legacy local bearer token, or your Insight/API-only license key -The local bearer token authenticates the caller. It does not bypass the mapped-circuit licensing limit. Generate a 256-bit token in **License & Services**, copy it into your API client before saving, and treat it like a password. Saved tokens are not displayed again; generate a replacement if the original is lost. +Local API keys authenticate callers; they do not bypass the mapped-circuit licensing limit. Administrators can create up to 16 named keys in **License & Services**. LibreQoS displays each generated key once, stores only its SHA-256 digest and non-secret metadata in `/etc/lqos.conf`, and cannot recover it later. Copy the complete `lqos_api_...` value into the client immediately and treat it like a password. + +Named keys do not expire automatically. Revoke keys that are no longer needed; creation and revocation may take up to 30 seconds to reach `lqos_api`. Existing license keys and the older single `local_api.bearer_token` remain compatible. The UI labels the older value as **Legacy local API key** and lets an administrator remove it after clients have moved to named keys. ## What ISPs Can Do with the API diff --git a/docs/v2.0/insight.md b/docs/v2.0/insight.md index 0d53be68..b5a321ee 100644 --- a/docs/v2.0/insight.md +++ b/docs/v2.0/insight.md @@ -125,7 +125,7 @@ Without a valid Insight or Local license/grant state, LibreQoS admits only the f A valid entitled license/grant state enables mapped-circuit counts above the default 1000 limit. -Starting with LibreQoS 2.2, the Node API uses this same unique valid mapped-circuit count. API access is available without an Insight subscription at 1,000 or fewer mapped circuits. Above 1,000, the API requires a valid live entitlement or locally cached signed grant. API clients must still authenticate with either a local API bearer token or an Insight/API-only license key. +Starting with LibreQoS 2.2, the Node API uses this same unique valid mapped-circuit count. API access is available without an Insight subscription at 1,000 or fewer mapped circuits. Above 1,000, the API requires a valid live entitlement or locally cached signed grant. API clients must still authenticate with a named local API key, the legacy local bearer token, or an Insight/API-only license key. Administrators create and revoke named keys in **License & Services**; changes reach `lqos_api` within 30 seconds. The default 1000-limit behavior applies when license/grant state is: - missing diff --git a/docs/v2.0/troubleshooting.md b/docs/v2.0/troubleshooting.md index 1e3598c4..1d414db6 100644 --- a/docs/v2.0/troubleshooting.md +++ b/docs/v2.0/troubleshooting.md @@ -350,7 +350,7 @@ Recommended checks: 2. Review `lqosd` logs for requested/allowed/dropped counts. 3. Reduce mapped circuit count (short term) or update licensing/limits (long term). -The Node API follows the same count starting with LibreQoS 2.2. At 1,000 or fewer mapped circuits, confirm that a local API bearer token is configured and that `lqos_api` is running. Above 1,000, also confirm that the effective API or Insight entitlement is valid. +The Node API follows the same count starting with LibreQoS 2.2. At 1,000 or fewer mapped circuits, confirm that a named local API key (or compatible legacy/license key) is configured and that `lqos_api` is running. New and revoked named keys may take up to 30 seconds to take effect. Above 1,000, also confirm that the effective API or Insight entitlement is valid. ### Urgent issue codes and first actions diff --git a/docs/v2.0/update.md b/docs/v2.0/update.md index bd889095..2db3ffa7 100644 --- a/docs/v2.0/update.md +++ b/docs/v2.0/update.md @@ -9,7 +9,7 @@ If you use the XDP bridge, traffic will briefly stop passing through the bridge ```{important} Starting in v2.0, mapped-circuit ingest depends on valid entitled license/grant state. Without a valid Insight or Local license/grant state, LibreQoS reads only the first 1000 valid mapped circuits into active shaping state. This includes expired or otherwise invalid local grant/license state. See [Insight Licensing Behavior](insight.md#mapped-circuit-limits-and-license-state) and [Troubleshooting](troubleshooting.md). -Starting in v2.2, the Node API uses the same mapped-circuit policy. Networks with 1,000 or fewer valid mapped circuits may use the API without an Insight subscription; larger networks require a valid API or Insight entitlement. API calls remain authenticated with a local API bearer token or an existing license key. +Starting in v2.2, the Node API uses the same mapped-circuit policy. Networks with 1,000 or fewer valid mapped circuits may use the API without an Insight subscription; larger networks require a valid API or Insight entitlement. API calls remain authenticated. Administrators can create up to 16 named local API keys in **License & Services**; keys are shown once, stored only as SHA-256 digests, and can be revoked. Existing license keys and the legacy local bearer token remain compatible, and key changes may take up to 30 seconds to take effect. ``` Run: