PD-1601 / 25.04 / Pd 1601 update docs for new versioned api

content/SCALE/API/_index.md

@@ -9,11 +9,29 @@ related: false
 
 {{< include file="/static/includes/RESTAPIDeprecationNotice.md" >}}
 
-You can access TrueNAS API documentation in the web interface by clicking **<i class="material-icons" aria-hidden="true">account_circle</i> > API Keys > API Docs**.
+{{< include file="/static/includes/APIKeyMigrate.md" >}}
+
+## API Documentation
+
+You can access TrueNAS API documentation in the web interface by clicking <i class="material-icons" aria-hidden="true" title="laptop" style="vertical-align: top;">laptop</i> **My API Keys** on the top right toolbar <i class="material-icons" aria-hidden="true">account_circle</i> user settings dropdown menu to open the **User API Keys** screen.
+Click **API Docs** to view API documentation.
 
 ![SCALEapidocs](/images/SCALE/Dashboard/APIKeysScreen.png "API Docs location")
 
 Alternatively, append `/api/docs/` to your TrueNAS host name or IP address in a browser to access the API documentation.
 
-For convenience, we store static builds of the current 2.0 API documentation on the Docs Hub:
-* [Websocket Protocol](/api/scale_websocket_api.html)
+{{< include file="/static/includes/APIDocs.md" >}}
+
+## API Access
+
+User-linked API access keys allow administrators to configure per-user access to the TrueNAS API.
+Keys are revokable and can be configured to automatically expire on a preset date.
+
+{{< include file="/static/includes/API_AD.md" >}}
+
+User-linked API keys allow for better integration of TrueNAS into third-party solutions.
+Use this as a reference for projects that require direct TrueNAS integration.
+
+{{< include file="/static/includes/APIKeyWarn.md" >}}
+
+See [Managing API Keys]({{< relref "/scale/scaletutorials/toptoolbar/managingapikeys.md" >}}) for more information.

content/SCALE/GettingStarted/SCALEReleaseNotes.md

@@ -54,6 +54,25 @@ More details are available from [Software Releases]({{< relref "/TrueNASUpgrades
 
 * {{< include file="/static/includes/RESTAPIDeprecationNotice.md" >}}
 
+  {{< include file="/static/includes/APIDocs.md" >}}
+
+  You can access TrueNAS API documentation in the web interface by clicking <i class="material-icons" aria-hidden="true" title="laptop" style="vertical-align: top;">laptop</i> **My API Keys** on the top right toolbar <i class="material-icons" aria-hidden="true">account_circle</i> user settings dropdown menu to open the **User API Keys** screen.
+  Click **API Docs** to view API documentation.
+
+* 25.04 also introduces user-linked API access keys, allowing administrators to configure per-user access to the TrueNAS API.
+  Keys are revokable and can be configured to automatically expire on a preset date.
+
+  {{< include file="/static/includes/API_AD.md" >}}
+
+  User-linked API keys allow for better integration of TrueNAS into third-party solutions.
+  Use this as a reference for projects that require direct TrueNAS integration.
+
+  {{< include file="/static/includes/APIKeyWarn.md" >}}
+
+  See [Managing API Keys]({{< relref "/scale/scaletutorials/toptoolbar/managingapikeys.md" >}}) for more information.
+
+  * {{< include file="/static/includes/APIKeyMigrate.md" >}}
+
 * The default libvirt account UID and GID is changed to to avoid possible clashes with user created Active Directory (AD) users. TrueNAS automatically updates libvirt UID and GIDs when upgraded to 25.04. Users attempting revert to 24.10 or an earlier release must manually review and update libvirt-qemu user and group IDs back to the values that were default in that version (64055:64055 for 24.10).
 
 ### Migrating Virtual Machines
@@ -117,11 +136,9 @@ For more details on feature flags, see [OpenZFS Feature Flags](https://openzfs.g
 
 ## 25.04 Nightly Development Changelog
 
-* The TrueNAS REST API is deprecated in TrueNAS 25.04 and replaced by the [TrueNAS websocket client](https://github.com/truenas/api_client). Full removal of the REST API is planned for a future release.
-* The default libvirt account UID & GID is changed to a less common value to avoid clashing with user created UID/GIDs. See Upgrade Notes above for more information ([NAS-131695](https://ixsystems.atlassian.net/browse/NAS-131695)).
+* The TrueNAS REST API is deprecated in TrueNAS 25.04 and replaced with a versioned JSON-RPC 2.0 over WebSocket API ([API Reference]({{< relref "/scale/api/_index.md" >}})). Full removal of the REST API is planned for a future release.
 * Improved API key mechanism with support for user-linked API keys ([NAS-131396](https://ixsystems.atlassian.net/browse/NAS-131396)).
-  Existing API keys created via the TrueNAS API (not UI or TrueCommand) that specify an allow list with white-listed API methods are revoked upon upgrade because there is no clean way to migrate to the new system.
-  Legacy API keys from TrueNAS 24.10 or earlier migrate to the root, admin, or truenas_admin account, depending on server configuration
+* The default libvirt account UID & GID is changed to a less common value to avoid clashing with user created UID/GIDs. See Upgrade Notes above for more information ([NAS-131695](https://ixsystems.atlassian.net/browse/NAS-131695)).
 
 <!--
 

content/SCALE/SCALETutorials/Credentials/ManageLocalGroups.md

@@ -52,6 +52,7 @@ This is not used for SMB authentication or determining the user session token or
 Click **Save**.
 
 ## Managing Groups
+
 Click anywhere on a row to expand that group and show the group management buttons.
 
 {{< trueimage src="/images/SCALE/Credentials/GroupsListedExpandedSCALE.png" alt="Expanded Group Screen" id="Expanded Group Screen" >}}

content/SCALE/SCALETutorials/Shares/SMB/_index.md

@@ -42,16 +42,6 @@ Windows clients use [WS-Discovery](https://docs.oasis-open.org/ws-dd/ns/discover
 Discoverability through broadcast protocols is a convenience feature and is not required to access an SMB server.
 {{< /hint >}}
 
-### SMB Share Limitations
-Sharing protocols have file-related limitations such as name and path lengths, permitted characters, file or volume size, permissions through access control lists (ACLs), and ACL entries based on the underlying client operating system (Windows, Linux, MacOS).
-SMB protocol version limits are based on the version (SMB1, SMB2, SMB3).
-
-There are limitations and issues related to using third-party file managers instead of native tools.
-
-For more on limits, click below.
-
-{{< include file="/static/includes/SMBLimitations.md" >}}
-
 ## Sharing Administrator Access
 
 {{< include file="/static/includes/SharingAdminRole.md" >}}

content/SCALE/SCALETutorials/SystemSettings/Advanced/_index.md

@@ -30,8 +30,7 @@ This article provides information on sysctl, system dataset pool, setting the ma
 
 ## Configuring System Auditing
 
-The **Audit** widget displays the current audit storage and retention policy settings. The public-facing API allows querying
-audit records, exporting audit reports, and configuring audit dataset settings and retention periods.
+The **Audit** widget displays the current audit storage and retention policy settings. The public-facing [TrueNAS API]({{< relref "/SCALE/API/_index.md" >}}) allows querying audit records, exporting audit reports, and configuring audit dataset settings and retention periods.
 
 {{< trueimage src="/images/SCALE/SystemSettings/SystemAdvancedAuditWidget.png" alt="Advanced System Setting Audit Widget" id="Advanced System Setting Audit Widget" >}}
 

content/SCALE/SCALETutorials/TopToolbar/ManagingAPIKeys.md

@@ -9,7 +9,13 @@ tags:
 - apikeys
 ---
 
-The <i class="material-icons" aria-hidden="true" title="laptop" style="vertical-align: top;">laptop</i> **My API Keys** option on the top right toolbar **Settings** (user icon) dropdown menu displays the **User API Keys** screen.
+TrueNAS 25.04 and later uses a versioned JSON-RPC 2.0 over WebSocket API with support for user-linked API access keys ([API Reference]({{< relref "/scale/api/_index.md" >}})).
+
+User-linked API keys allow administrators to configure per-user access to the TrueNAS API.
+Keys are revokable and can be configured to automatically expire on a preset date.
+
+Click <i class="material-icons" aria-hidden="true" title="laptop" style="vertical-align: top;">laptop</i> **My API Keys** on the top right toolbar <i class="material-icons" aria-hidden="true">account_circle</i> user settings dropdown menu to open the **User API Keys** screen.
+
 This screen displays a list of API keys added to your system and allows you to add, search, edit, or delete keys.
 Click **API Docs** to view [API Documentation](#api-documentation).
 
@@ -26,17 +32,20 @@ Click **Add** to open the **Add API Key** screen.
 Type a descriptive name for the key.
 Use the **Username** dropdown to select an administrative user to associate with this key.
 
+{{< include file="/static/includes/API_AD.md" >}}
+
 Accept the default **Non-expiring** to create a token with no expiration date.
 A non-expiring key remains active until it is manually revoked or updated.
 
 To create a key with a scheduled expiration, click to clear the **Non-expiring** checkbox.
-Click on the **Expires at** field and use the calendar dropdown to select the expiration date.
+Click on the **Expires On** field and use the calendar dropdown to select the expiration date.
 
 {{< trueimage src="/images/SCALE/Dashboard/APIKeyExpires.png" alt="Key Expiration Settings" id="Key Expiration Settings" >}}
 
 Click **Save** to generate the key.
 
-TrueNAS displays an **API Key** dialog containing the generated key value.
+TrueNAS displays an **API Key** dialog containing the generated key string.
+TrueNAS API key strings are 64 characters long and randomly generated.
 
 {{< trueimage src="/images/SCALE/Dashboard/APIKeyCopy.png" alt="API Key Success Dialog" id="API Key Success Dialog" >}}
 
@@ -54,11 +63,10 @@ Click <i class="material-icons" aria-hidden="true" title="Edit">edit</i> edit fo
 
 {{< trueimage src="/images/SCALE/Dashboard/APIKeysEdit.png" alt="Edit API Key" id="Edit API Key" >}}
 
-Select the **Reset** to remove the existing API key and generate a new random key.
+Select **Reset** to remove the existing API key string and generate a new random key.
 The dialog displays the new key and the **Copy to Clipboard** option.
 Click to copy the new API key string then save it in a secure location.
-
-{{< include file="/static/includes/APIKeyWarn.md" >}}
+Update any clients using the reset API Key with the new key string.
 
 ### Deleting an API Key
 
@@ -71,4 +79,6 @@ Select **Confirm** then click **Delete**.
 
 ## API Documentation
 
-Click **API Docs** to access the TrueNAS API documentation that is built into the system.
+Click **API Docs** to access the TrueNAS API documentation built into the system.
+
+{{< include file="/static/includes/APIDocs.md" >}}

content/SCALE/SCALEUIReference/Credentials/LocalGroupsScreens.md

@@ -53,6 +53,7 @@ Click **Add** to open the **Add Group** configuration screen.
 {{< /truetable >}}
 
 ## Edit Group Screen
+
 Click **Edit** on an expanded group in the **Groups** screen to open the **Edit Group** screen.
 
 {{< trueimage src="/images/SCALE/Credentials/EditGroup.png" alt="Edit Group Screen" id="Edit Group Screen" >}}

content/SCALE/SCALEUIReference/SystemSettings/AdvancedSettingsScreen.md

@@ -91,8 +91,7 @@ There are also options to configure a remote syslog server for recording system
 {{< /expand >}}
 
 ## Audit Widget
-The **Audit** widget displays the current audit storage and retention policy settings. The public-facing API allows querying
-audit records, exporting audit reports, and configuring audit dataset settings and retention periods.
+The **Audit** widget displays the current audit storage and retention policy settings. The public-facing [TrueNAS API]({{< relref "/SCALE/API/_index.md" >}}) allows querying audit records, exporting audit reports, and configuring audit dataset settings and retention periods.
 
 {{< trueimage src="/images/SCALE/SystemSettings/SystemAdvancedAuditWidget.png" alt="Advanced System Setting Audit Widget" id="Advanced System Setting Audit Widget" >}}
 

content/SCALE/SCALEUIReference/TopToolbar/Settings/APIKeysScreen.md

@@ -9,7 +9,8 @@ tags:
 - toolbar
 ---
 
-The <i class="material-icons" aria-hidden="true" title="laptop" style="vertical-align: top;">laptop</i> **My API Keys** option on the top right toolbar **Settings** (user icon) dropdown menu displays the **User API Keys** screen.
+<i class="material-icons" aria-hidden="true" title="laptop" style="vertical-align: top;">laptop</i> **My API Keys** on the top right toolbar <i class="material-icons" aria-hidden="true">account_circle</i> user settings dropdown menu to opens the **User API Keys** screen.
+
 This screen displays a list of API keys added to your system and allows you to add, search, edit, or delete keys.
 **API Docs** opens the [API Documentation](#api-documentation).
 
@@ -21,7 +22,7 @@ This screen displays a list of API keys added to your system and allows you to a
 
 {{< include file="/static/includes/APIKeyWarn.md" >}}
 
-<i class="material-icons" aria-hidden="true" title="Edit">edit</i> edit for any API key on the list openss the **Edit API Key** window to modify that key.
+<i class="material-icons" aria-hidden="true" title="Edit">edit</i> edit for any API key on the list opens the **Edit API Key** window to modify that key.
 
 {{< trueimage src="/images/SCALE/Dashboard/APIKeysEdit.png" alt="Edit API Key" id="Edit API Key" >}}
 
@@ -34,3 +35,5 @@ This screen displays a list of API keys added to your system and allows you to a
 ## API Documentation
 
 **API Docs** opens the TrueNAS API documentation that is built into the system.
+
+{{< include file="/static/includes/APIDocs.md" >}}

content/SCALE/SCALEUIReference/TopToolbar/Settings/_index.md

@@ -8,16 +8,17 @@ tags:
 - toolbar
 ---
 
-The <span class="material-icons">account_circle</span> **Settings** icon button displays a menu of general system settings options. 
-The options are **Change Password**, **Preferences**, **API Keys**, **Guide** and **About**.
+The <span class="material-icons">account_circle</span> **Settings** icon button displays a menu of general system settings options.
+The options are **Change Password**, **Preferences**, **My API Keys**, **Guide** and **About**.
 
 ## Change Password
 
 {{< include file="/static/includes/ChangeLoggedInUserPassword.md" >}}
 
-## API Keys
+## My API Keys
 
-Click on <span class="material-icons">laptop</span> **API Keys** to display the **API Keys** screen where you can add new or manage existing API keys on your system.
+Click on <span class="material-icons">laptop</span> **My API Keys** to display the **User API Keys** screen where you can add or manage API keys on your system.
+Click **API Docs** on the **User API Keys** screen to view API documentation.
 
 ## Guide
 

static/includes/25.04FeatureList.md

@@ -7,18 +7,16 @@
 
 * iSCSI Fibre Channel support (Enterprise Feature)
 
-* Versioned TrueNAS API
+* Versioned TrueNAS JSON-RPC 2.0 over WebSocket API (see [API Reference]({{< relref "/SCALE/API/_index.md" >}}))
 
 * User-linked API Keys (see [Managing API Keys]({{< relref "/scale/scaletutorials/toptoolbar/managingapikeys.md" >}}))
 
-* Improved UI Login Experience ([NAS-130810](https://ixsystems.atlassian.net/browse/NAS-130810)).
+* Improved UI Login Experience ([NAS-130810](https://ixsystems.atlassian.net/browse/NAS-130810))
 
 * Improved STIG Compliance and Security Focus ([NAS-127235](https://ixsystems.atlassian.net/browse/NAS-127235))
 
 * Enable support for ZFS Fast Deduplication ([NAS-127088](https://ixsystems.atlassian.net/browse/NAS-127088))
 
-<--->
-
 * New and improved [virtualization]({{< relref "/scale/scaletutorials/virtualization/_index.md" >}}) features.
 
   {{< include file="/static/includes/incus.md" >}}

static/includes/APIDocs.md

@@ -0,0 +1,12 @@
+

+
+TrueNAS 25.04 and later uses a versioned JSON-RPC 2.0 over WebSocket API.
+API versions are numbered in conjunction with TrueNAS version releases.
+
+The API documentation provides information about supported API methods and events.
+Documentation is included for all API versions supported by the current TrueNAS release and defaults to the latest supported API.
+Use the dropdown to view documentation for different supported API versions.
+
+Advanced users can interact with the TrueNAS API to perform management tasks using the [TrueNAS API Client](https://github.com/truenas/api_client) as an alternative to the TrueNAS web UI.
+This websocket client provides the command line tool `midclt` and allows users to communicate with middleware using Python by making API calls.
+The client can connect to the local TrueNAS instance or to a specified remote socket.

static/includes/APIKeyMigrate.md

@@ -0,0 +1,6 @@
+

+
+Legacy API keys created in TrueNAS 24.10 or earlier migrate to the root, admin, or truenas_admin account, depending on server configuration.
+
+Existing API keys created via the TrueNAS API (not UI or TrueCommand) that specify an allow list with white-listed API methods are revoked upon upgrade because there is no clean way to migrate to the new system.
+Administrators should create a service account (a user account for this particular purpose), define desired access rights for this service account, [generate a new user-linked API key]({{< relref "/scale/scaletutorials/toptoolbar/managingapikeys.md" >}}), and distribute it to the API client.

static/includes/APIKeyWarn.md

@@ -1,6 +1,16 @@
 

 
-{{< hint type=warning >}}
+{{< hint type=warning title="API Key Security" >}}
 Always back up and secure keys.
-TrueNAS displays the key string only one time after creation, in the **API Key** confirmation dialog.
+TrueNAS displays the key string only once, in the **API Key** confirmation dialog, immediately after creation.
+
+User-linked API keys allow password-equivalent access to the TrueNAS middleware.
+API keys are not subject to the two-factor authentication (2FA) configuration of the associated user account.
+A compromised API key results in access to the TrueNAS API as the associated user, even if the account is configured to require 2FA.
+
+For increased security, HTTPS with SSL/TLS transport security is required for TrueNAS API authentication using API keys.
+TrueNAS automatically revokes any user-linked API keys passed as part of an authentication attempt via insecure (HTTP) transport.
+A revoked API key cannot be used until it is reset.
+Resetting generates a new key-string.
+Remember to update clients to use the new key.
 {{< /hint >}}

static/includes/API_AD.md

@@ -0,0 +1,5 @@
+

+
+{{< hint type=note >}}
+Active Directory/LDAP user-linked API key support is available to TrueNAS Enterprise customers only.
+{{< /hint >}}

static/includes/RESTAPIDeprecationNotice.md

@@ -1,15 +1,6 @@
 

 
 {{< hint type="info" title="REST API Deprecation Notice" >}}
-The TrueNAS REST API is deprecated in TrueNAS 25.04 and replaced by the [TrueNAS websocket client](https://github.com/truenas/api_client).
+The TrueNAS REST API is deprecated in TrueNAS 25.04.
 Full removal of the REST API is planned for a future release.
-
-This new API Client is not the deprecated TrueNAS CLI (midcli).
-The API Client is integrated in TrueNAS 25.04 onwards.
-It provides the `midclt` command-line tool, and the means to easily communicate with middleware using Python to make calls through the websocket API.
-
-This API client allows for better integration of TrueNAS into third-party solutions.
-Use this as a reference for projects that require direct TrueNAS integration.
-
-TrueNAS API documentation remains available in the UI and through the [TrueNAS Documentation Hub]({{< relref "/content/SCALE/api/_index.md" >}}).
 {{< /hint >}}