juemerson-at-purestorage · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026
diff --git a/Public/Admin/New-PfbApiClient.ps1 b/Public/Admin/New-PfbApiClient.ps1
@@ -4,41 +4,74 @@ function New-PfbApiClient {
         Creates a new API client on the FlashBlade.
     .DESCRIPTION
         The New-PfbApiClient cmdlet creates a new API client on the connected Pure Storage
-        FlashBlade. API clients are used for OAuth2 authentication and require at minimum
-        a public key and a maximum role assignment.
+        FlashBlade. API clients require a public key. On REST 2.0-2.18, they also require
+        a maximum role assignment; from REST 2.19 onward, max_role is deprecated in favour
+        of access_policies.
+
+        The typed parameters and the raw -Attributes hashtable are mutually exclusive: they
+        live in separate parameter sets, so PowerShell rejects a mixed invocation at bind time
+        rather than letting -Attributes silently override an explicitly supplied value.
     .PARAMETER Name
         The name of the API client to create.
+    .PARAMETER PublicKey
+        The public key for the API client. Required by the API client's POST body schema.
+    .PARAMETER MaxRole
+        The maximum role assignment for the API client. The API requires this on REST 2.0-2.18;
+        it is deprecated in favour of access_policies from REST 2.19 onward.
     .PARAMETER Attributes
-        A hashtable defining the API client properties, including the public key and role.
+        A raw hashtable defining the API client properties. This parameter is mutually exclusive
+        with the typed parameters. When using -Attributes, the caller is responsible for supplying
+        the required public_key (and max_role on REST 2.0-2.18).
     .PARAMETER Array
         The FlashBlade connection object. If not specified, the default connection is used.
     .EXAMPLE
-        New-PfbApiClient -Name 'automation-client' -Attributes @{ max_role = @{ name = 'storage_admin' }; public_key = $key }
+        New-PfbApiClient -Name 'automation-client' -PublicKey $key -MaxRole 'storage_admin'
 
         Creates a new API client with the storage_admin role and the specified public key.
     .EXAMPLE
-        New-PfbApiClient -Name 'readonly-client' -Attributes @{ max_role = @{ name = 'readonly' }; public_key = $key }
+        New-PfbApiClient -Name 'readonly-client' -PublicKey $key
 
-        Creates a new read-only API client.
+        Creates a new API client with the specified public key. On REST 2.0-2.18, supply
+        -MaxRole as well; from REST 2.19 onward, max_role is deprecated in favour of access_policies.
     .EXAMPLE
         New-PfbApiClient -Name 'ops-client' -Attributes @{ max_role = @{ name = 'ops_admin' }; public_key = $key } -Confirm:$false
 
-        Creates a new API client without prompting for confirmation.
+        Creates a new API client from a hand-rolled body without prompting for confirmation.
+        When using -Attributes, the caller is responsible for supplying the required public_key.
     #>
-    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
+    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium',
+                   DefaultParameterSetName = 'Typed')]
     param(
-        [Parameter(Mandatory, Position = 0)]
+        [Parameter(ParameterSetName = 'Typed', Mandatory, Position = 0)]
+        [Parameter(ParameterSetName = 'Attributes', Mandatory, Position = 0)]
         [string]$Name,
 
-        [Parameter()]
+        [Parameter(ParameterSetName = 'Typed', Mandatory)]
+        [string]$PublicKey,
+
+        [Parameter(ParameterSetName = 'Typed')]
+        [string]$MaxRole,
+
+        [Parameter(ParameterSetName = 'Attributes', Mandatory)]
         [hashtable]$Attributes,
 
         [Parameter()] [PSCustomObject]$Array
     )
 
     Assert-PfbConnection -Array ([ref]$Array)
 
-    $body = if ($Attributes) { $Attributes } else { @{} }
+    if ($PSCmdlet.ParameterSetName -eq 'Attributes') {
+        $body = $Attributes.Clone()
+    }
+    else {
+        $body = @{ public_key = $PublicKey }
+        # max_role is a scalar reference ({id, name, resource_type}); resource_type
+        # is readOnly and must never be sent.
+        if ($PSBoundParameters.ContainsKey('MaxRole')) {
+            $body['max_role'] = @{ name = $MaxRole }
+        }
+    }
+
     $queryParams = @{ 'names' = $Name }
 
     if ($PSCmdlet.ShouldProcess($Name, 'Create API client')) {

diff --git a/Public/Misc/Update-PfbLegalHoldEntity.ps1 b/Public/Misc/Update-PfbLegalHoldEntity.ps1
@@ -3,11 +3,22 @@ function Update-PfbLegalHoldEntity {
     .SYNOPSIS
         Updates a held entity under a legal hold on the FlashBlade.
     .DESCRIPTION
-        The Update-PfbLegalHoldEntity cmdlet modifies the properties of an entity that is
-        subject to a legal hold on the connected Pure Storage FlashBlade. Identify the
-        held entity by name and supply the changed properties via Attributes.
+        The Update-PfbLegalHoldEntity cmdlet applies or releases a legal hold over a
+        file-system path on the connected Pure Storage FlashBlade. `released` is required
+        by the API, so -Released must always be supplied: `$true` releases the hold,
+        `$false` applies it.
+
+        A held entity has no name of its own -- `LegalHoldHeldEntity` carries only
+        `file_system`, `legal_hold`, `path` and `status` -- so it is addressed by the
+        file system plus the path, together with -Recursive. Measured on a live array
+        (Purity//FB 4.8.2, REST 2.26): a request naming only the hold is rejected with
+        "Either names or ids query parameter is required", and one naming the file system
+        and path but omitting -Recursive is rejected with "Can't apply or release legal
+        holds to directories without the recursive flag provided". Both directions behave
+        identically here, so a release is symmetric with an apply rather than special.
     .PARAMETER Name
-        The name of the held entity to update.
+        The name of the legal hold. Sent as `names`, which the endpoint declares but which
+        does not on its own identify a held entity -- see the description above.
     .PARAMETER FileSystemIds
         The IDs of the file systems whose held entities to update.
     .PARAMETER FileSystemNames
@@ -20,25 +31,30 @@ function Update-PfbLegalHoldEntity {
         If set to `true`, the update is applied recursively to the specified path or file
         system.
     .PARAMETER Released
-        If set to `true`, the held entity is released from its legal hold.
+        Required by the API on REST 2.17 and later. `$true` releases the held entity from its
+        legal hold; `$false` applies or keeps the legal hold.
     .PARAMETER Attributes
         A hashtable of attributes to update on the held entity. `PATCH
         /legal-holds/held-entities` accepts no request body, so nothing supplied here is sent
         to the array. Use the typed query parameters above instead.
     .PARAMETER Array
         The FlashBlade connection object. If not specified, the default connection is used.
     .EXAMPLE
-        Update-PfbLegalHoldEntity -Name "fs1" -Released $true
+        Update-PfbLegalHoldEntity -Name 'pslivetest-hold-1' -FileSystemNames 'pslivetest-fs-1' -Paths '/' -Recursive $true -Released $true
 
-        Releases the held entity named "fs1" from its legal hold.
+        Releases the held entity named "pslivetest-hold-1" from its legal hold. The file-system
+        name, path, and recursive flag are all required together for this release request.
     .EXAMPLE
-        Update-PfbLegalHoldEntity -Name "bucket1" -Recursive $false
+        Update-PfbLegalHoldEntity -Name 'pslivetest-hold-1' -FileSystemNames 'pslivetest-fs-1' -Paths '/' -Recursive $true -Released $false
 
-        Updates the held entity named "bucket1" without applying the change recursively.
+        Applies the legal hold to the same path. This is the release example with -Released
+        flipped -- the two directions take the same arguments.
     .EXAMPLE
-        Update-PfbLegalHoldEntity -Name "fs1" -Attributes @{ hold_type = 'litigation' }
+        Update-PfbLegalHoldEntity -Name 'pslivetest-hold-1' -FileSystemIds '10314f42-020d-7080-8013-000ddt400090' -Paths '/' -Recursive $true -Released $true
 
-        Updates the held entity using a raw attributes hashtable.
+        Releases the hold identifying the file system by ID instead of by name. Note that
+        `file_system_ids` refers to the file system, which has an ID; the held entity itself
+        does not, so -Ids is not a substitute for this form.
     #>
     [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
     param(
@@ -60,8 +76,8 @@ function Update-PfbLegalHoldEntity {
         [Parameter()]
         [Nullable[bool]]$Recursive,
 
-        [Parameter()]
-        [Nullable[bool]]$Released,
+        [Parameter(Mandatory)]
+        [bool]$Released,
 
         [Parameter()]
         [hashtable]$Attributes,
@@ -88,7 +104,9 @@ function Update-PfbLegalHoldEntity {
         if ($PSBoundParameters.ContainsKey('Ids'))              { $queryParams['ids']               = $Ids -join ',' }
         if ($PSBoundParameters.ContainsKey('Paths'))            { $queryParams['paths']             = $Paths -join ',' }
         if ($PSBoundParameters.ContainsKey('Recursive'))        { $queryParams['recursive']         = $Recursive }
-        if ($PSBoundParameters.ContainsKey('Released'))         { $queryParams['released']          = $Released }
+        # Unlike optional parameters, released is required by the spec, so no legal request omits it;
+        # the usual ContainsKey distinction between omitted and supplied as false cannot arise here.
+        $queryParams['released'] = $Released
 
         if ($PSCmdlet.ShouldProcess($Name, 'Update legal hold entity')) {
             Invoke-PfbApiRequest -Array $Array -Method PATCH -Endpoint 'legal-holds/held-entities' -Body $body -QueryParams $queryParams

diff --git a/Reports/PfbApiDriftReport.json b/Reports/PfbApiDriftReport.json
@@ -9267,9 +9267,9 @@
           "enumStatus": "no-spec-enum-found",
           "target": {
             "file": "Public/Admin/New-PfbApiClient.ps1",
-            "paramBlockLine": 36,
+            "paramBlockLine": 58,
             "payloadVariable": "body",
-            "assignmentStyle": "unknown",
+            "assignmentStyle": "literal",
             "hasAttributes": true
           }
         },
@@ -9284,9 +9284,9 @@
           "enumStatus": "no-spec-enum-found",
           "target": {
             "file": "Public/Admin/New-PfbApiClient.ps1",
-            "paramBlockLine": 36,
+            "paramBlockLine": 58,
             "payloadVariable": "body",
-            "assignmentStyle": "unknown",
+            "assignmentStyle": "literal",
             "hasAttributes": true
           }
         },
@@ -9301,43 +9301,9 @@
           "enumStatus": "no-spec-enum-found",
           "target": {
             "file": "Public/Admin/New-PfbApiClient.ps1",
-            "paramBlockLine": 36,
-            "payloadVariable": "body",
-            "assignmentStyle": "unknown",
-            "hasAttributes": true
-          }
-        },
-        {
-          "name": "max_role",
-          "type": null,
-          "format": null,
-          "specRequired": false,
-          "synopsis": "Deprecated.",
-          "suggestedPowerShellType": "[object]",
-          "enumValues": [],
-          "enumStatus": "no-spec-enum-found",
-          "target": {
-            "file": "Public/Admin/New-PfbApiClient.ps1",
-            "paramBlockLine": 36,
-            "payloadVariable": "body",
-            "assignmentStyle": "unknown",
-            "hasAttributes": true
-          }
-        },
-        {
-          "name": "public_key",
-          "type": "string",
-          "format": null,
-          "specRequired": true,
-          "synopsis": "The API client's PEM formatted (Base64 encoded) RSA public key.",
-          "suggestedPowerShellType": "[string]",
-          "enumValues": [],
-          "enumStatus": "no-spec-enum-found",
-          "target": {
-            "file": "Public/Admin/New-PfbApiClient.ps1",
-            "paramBlockLine": 36,
+            "paramBlockLine": 58,
             "payloadVariable": "body",
-            "assignmentStyle": "unknown",
+            "assignmentStyle": "literal",
             "hasAttributes": true
           }
         }
@@ -15532,17 +15498,6 @@
       ],
       "annotations": []
     },
-    {
-      "name": "max_role",
-      "endpointCount": 2,
-      "queryEndpointCount": 0,
-      "bodyEndpointCount": 2,
-      "endpoints": [
-        "PATCH /api-clients",
-        "POST /api-clients"
-      ],
-      "annotations": []
-    },
     {
       "name": "member_sids",
       "endpointCount": 2,
@@ -15686,17 +15641,6 @@
       ],
       "annotations": []
     },
-    {
-      "name": "public_key",
-      "endpointCount": 2,
-      "queryEndpointCount": 0,
-      "bodyEndpointCount": 2,
-      "endpoints": [
-        "POST /api-clients",
-        "POST /public-keys"
-      ],
-      "annotations": []
-    },
     {
       "name": "qos_configurations",
       "endpointCount": 2,
@@ -16679,6 +16623,16 @@
       ],
       "annotations": []
     },
+    {
+      "name": "max_role",
+      "endpointCount": 1,
+      "queryEndpointCount": 0,
+      "bodyEndpointCount": 1,
+      "endpoints": [
+        "PATCH /api-clients"
+      ],
+      "annotations": []
+    },
     {
       "name": "max_session_duration",
       "endpointCount": 1,
@@ -16929,6 +16883,16 @@
       ],
       "annotations": []
     },
+    {
+      "name": "public_key",
+      "endpointCount": 1,
+      "queryEndpointCount": 0,
+      "bodyEndpointCount": 1,
+      "endpoints": [
+        "POST /public-keys"
+      ],
+      "annotations": []
+    },
     {
       "name": "purity_defined",
       "endpointCount": 1,
@@ -19246,6 +19210,14 @@
         "Remove-PfbFileSystemSession"
       ]
     },
+    {
+      "name": "public_key",
+      "cmdletCount": 2,
+      "cmdlets": [
+        "New-PfbApiClient",
+        "Update-PfbAdmin"
+      ]
+    },
     {
       "name": "recursive",
       "cmdletCount": 2,
@@ -19558,6 +19530,13 @@
         "Update-PfbAdmin"
       ]
     },
+    {
+      "name": "max_role",
+      "cmdletCount": 1,
+      "cmdlets": [
+        "New-PfbApiClient"
+      ]
+    },
     {
       "name": "max_session_duration",
       "cmdletCount": 1,
@@ -19663,13 +19642,6 @@
         "Get-PfbArrayPerformance"
       ]
     },
-    {
-      "name": "public_key",
-      "cmdletCount": 1,
-      "cmdlets": [
-        "Update-PfbAdmin"
-      ]
-    },
     {
       "name": "rdma_enabled",
       "cmdletCount": 1,
@@ -20072,11 +20044,6 @@
       "cmdletCount": 0,
       "cmdlets": []
     },
-    {
-      "name": "max_role",
-      "cmdletCount": 0,
-      "cmdlets": []
-    },
     {
       "name": "member_sids",
       "cmdletCount": 0,

diff --git a/Reports/PfbApiDriftReport.md b/Reports/PfbApiDriftReport.md
@@ -22,7 +22,7 @@ This report accepts **false positives in order to eliminate false negatives**. A
 
 - Uncovered endpoints: 95
 - Endpoints with parameter gaps: 439
-- Missing body properties (addable): 426
+- Missing body properties (addable): 424
 - Missing query parameters (addable): 880
 - Read-only body fields (not addable -- see the Read-only fields section below): 384
 - Phantom fields silently excluded (accumulated in the capability map, absent from the newest analysed spec): 40
@@ -414,7 +414,7 @@ Endpoints an existing cmdlet already calls, where the capability map knows of a
 | `POST /admins/api-tokens` | New-PfbApiToken | context_names |  | `high` |  |
 | `POST /admins/management-access-policies` | New-PfbAdminManagementAccessPolicy | context_names |  | `high` | POST/PATCH/DELETE return 403 regardless of account; not an implementation bug |
 | `POST /admins/ssh-certificate-authority-policies` | New-PfbAdminSshCaPolicy | context_names |  | `high` |  |
-| `POST /api-clients` | New-PfbApiClient |  | access_policies, access_token_ttl_in_ms, issuer, max_role, public_key | `high` |  |
+| `POST /api-clients` | New-PfbApiClient |  | access_policies, access_token_ttl_in_ms, issuer | `high` |  |
 | `POST /array-connections` | New-PfbArrayConnection | context_names |  | `high` |  |
 | `POST /arrays/erasures` | New-PfbArrayErasure | eradicate_all_data, preserve_configuration_data, skip_phonehome_check |  | `high` |  |
 | `POST /arrays/ssh-certificate-authority-policies` | New-PfbArraySshCaPolicy | context_names |  | `high` |  |