docs: osquery-based enrollment for Fleet, 2026-05-01 API, auto-approval curl

- Enrollment guide: add an osquery-based enrollment section for Fleet, and
  move the device API examples to the 2026-05-01 API version.
- Fleet tutorial: describe Linux enrollment as ACME Device Attestation with
  the TPM, and show the curl flow for adding Fleet to autoApproveSources via
  the Device Enrollment Policy API, since the console doesn't expose it.
- Agent guide and troubleshooting: tighten the wording around
  pre-registration and the duplicate-registration symptom.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017MzPzeUonmnLSsg2KvYgAK

Author: tashian

platform/enrollment-guide.mdx

@@ -31,7 +31,7 @@ into your Smallstep inventory:
 You can [manually invite users
 to join your Smallstep team](https://smallstep.com/app/?next=/users/invite),
 and they will be able to self-enroll devices
-using the [Smallstep Agent](./smallstep-agent.mdx).
+using the [Smallstep Agent](./smallstep-agent.mdx)'s `step-agent register` subcommand.
 
 By default, administrators
 must approve a new device
@@ -69,32 +69,33 @@ until Smallstep receives an attestation from the device.
 For a concrete example,
 see [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx)
 
+### Use osquery-based enrollment
+
+For [Fleet-managed](../tutorials/connect-fleet-dm-to-smallstep.mdx) Linux and Windows hosts, deploy the Smallstep osquery extension.
+The osquery extension will report each device's TPM Endorsement Key to Fleet.
+Smallstep then syncs the data into your inventory.
+
 ### Add devices via API
 
 You can import devices from any source into Smallstep using our API.
+
 Use this when your devices are inventoried in a system that Smallstep can't sync from.
-If Smallstep already syncs your inventory from an MDM,
-don't add the same devices via the API as well:
-the result is a duplicate entry that blocks agent enrollment.
-For Fleet-managed Linux and Windows hosts,
-deploy the [Smallstep osquery extension](../tutorials/connect-fleet-dm-to-smallstep.mdx#linux)
-so that Fleet reports each device's TPM Endorsement Key to Smallstep.
 
 Devices added via API are automatically approved.
 but they will not be marked as high-assurance
 until Smallstep receives an attestation from the device.
 
 You'll need [an API token](https://smallstep.com/app/?next=/settings/api/tokens/add) with all “device” scopes (put-device, patch-device, etc.).
 
-Use the [Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) endpoint to create a device.
+Use the [Add Device](https://gateway.smallstep.com/v2026-05-01/operations/PostDevices) endpoint to create a device.
 - For Apple devices, the `permanentIdentifier` must be the device's 9-character serial number.
 - For TPM 2.0 devices, the `permanentIdentifier` must be the TPM Endorsement Key URI, in the format `urn:ek:sha256:ul3sYf6uQ6jVEXAMPLEXoAuHI10U8gTvEJ6bMj95LXI=`. (You can retrieve the EK URI by running `step agent tpm --fingerprint` on the device.)
 - To create and assign a user to a device, fill in the `user` fields.
 
 Once added,
 the devices will be automatically approved.
 
-You can see the device using the [List Devices](https://gateway.smallstep.com/v2025-01-01/operations/ListDevices) endpoint:
+You can see the device using the [List Devices](https://gateway.smallstep.com/v2026-05-01/operations/ListDevices) endpoint:
 
 ```bash
 set +o history
@@ -103,7 +104,7 @@ set -o history
 curl -sH @api_headers --request GET \
   --url https://gateway.smallstep.com/api/devices \
   --header 'Accept: application/json' \
-  --header 'x-smallstep-api-version: 2025-01-01' | jq
+  --header 'x-smallstep-api-version: 2026-05-01' | jq
 ```
 
 You'll also see new devices in the Smallstep console,

platform/smallstep-agent.mdx

@@ -22,7 +22,7 @@ Using an MDM? See:
 - [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx) (macOS)
 - [Connect Intune to Smallstep](../tutorials/connect-intune-to-smallstep.mdx) (Windows)
 - [Connect Workspace ONE to Smallstep](../tutorials/connect-workspace-one-to-smallstep.mdx) (Windows)
-- [Connect Fleet DM to Smallstep](../tutorials/connect-fleet-dm-to-smallstep.mdx) (macOS, Linux, Windows)
+- [Connect Fleet DM to Smallstep](../tutorials/connect-fleet-dm-to-smallstep.mdx)
 </Alert>
 
 Running into trouble? See the [Smallstep Agent troubleshooting guide](./troubleshooting-agent.mdx).
@@ -356,7 +356,7 @@ so a host with no <code>/dev/tpmrm0</code> cannot enroll yet.
     ```
     
 
-## Registering and approving endpoints
+## Registering and approving NixOS endpoints
 
 ### Self-registration
 
@@ -388,8 +388,6 @@ If your devices are inventoried in a system that Smallstep can't sync from, you
        - Select the Smallstep Agents authority
        - Use the sha256 Root fingerprint displayed on this page
 
-If Smallstep already syncs your inventory from an MDM that reports each device's TPM Endorsement Key, such as Fleet with the Smallstep osquery extension, skip step 1. The devices are already in your inventory, and adding them again via the API or with `step-agent register` creates a conflicting entry. Write `agent.yaml` as in step 2 and start the agent. It attests with its TPM and is matched to the synced entry. See [Connect Fleet DM to Smallstep](../tutorials/connect-fleet-dm-to-smallstep.mdx#linux) for the full Fleet flow.
-
 ## Start the agent
 
 Finally, enable and start the agent:

platform/troubleshooting-agent.mdx

@@ -99,10 +99,10 @@ The agent may not be installed or may not be running on the device.
 
 **Symptom:** "`step-agent register` fails with `unprocessable entity`, or the browser prompts me to register a device that is already in my inventory"
 
-The device already exists in your Smallstep inventory. This happens when the device was synced from an MDM that reports its TPM Endorsement Key (for example, Fleet with the Smallstep osquery extension) or was added via the API. `step-agent register` tries to create a second device entry, which conflicts with the existing one.
+This happens when the device was synced from an MDM that reports its TPM Endorsement Key or was added via the API. `step-agent register` tries to create a second device entry, which conflicts with the existing one.
 
 **Troubleshooting steps:**
-1. Don't run `step-agent register` on the device. Write the agent configuration file directly and start the agent service. It attests with its TPM and is matched to the existing entry. See [Linux agent configuration](../tutorials/connect-fleet-dm-to-smallstep.mdx#step-5-linux-agent-configuration) in the Fleet tutorial, or [Pre-registration via API](./smallstep-agent.mdx#pre-registration-via-api) in the agent guide.
+1. Don't run `step-agent register` on the device. Write the agent configuration file directly and start the agent service. See [Pre-registration via API](./smallstep-agent.mdx#pre-registration-via-api).
 2. If a duplicate device was created, delete it in the [Smallstep console](https://smallstep.com/app/?next=/devices) and keep the entry that came from the MDM sync or the API.
 3. If the device shows as pending after the agent starts, approve it in the console.
 

tutorials/connect-fleet-dm-to-smallstep.mdx

@@ -404,10 +404,13 @@ Once the enrollment report is configured in Fleet, the Smallstep platform needs
 2. In the Smallstep console, edit your Fleet configuration
 3. Set the **Enrollment Query ID** to the numeric ID
 
+Your fleet's TPM information will begin syncing to Smallstep.
 
 ## Step 5. Linux agent configuration
 
-Linux does not support MDM configuration profiles, so the SCEP enrollment flow used for macOS and Windows does not apply. Instead, the Smallstep agent on Linux registers directly using TPM attestation. After installing the agent package and the osquery extension, you must configure the agent with your Smallstep team slug and CA fingerprint.
+Linux does not support MDM configuration profiles, so the SCEP enrollment flow used for macOS and Windows does not apply. Instead, the Smallstep agent on Linux uses ACME Device Attestation with the system's TPM.
+
+After installing the agent package and the osquery extension, you must configure the agent with your Smallstep team slug and CA fingerprint.
 
 When adding a Linux agent package in Fleet, add the following **post-install script** to configure and start the agent:
 
@@ -426,14 +429,34 @@ systemctl daemon-reload
 systemctl enable --now step-agent
 ```
 
+When the agent starts, it attests with the endpoint's TPM. Smallstep matches the attestation to the inventory data you just synced. By default, devices synced from Fleet need admin approval: if the host shows as `pending` in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there.
 
-When the agent starts, it attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. No registration step runs on the host. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy).
+To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` in your team's device enrollment policy. This setting isn't exposed in the Smallstep console. Use the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy) with an [API token](https://smallstep.com/app/?next=/settings/api/tokens/add) that has the `get-device-enrollment-policy` and `put-device-enrollment-policy` scopes. The `PUT` replaces the whole policy, so fetch the current policy first and resubmit it with `Fleet` added to `autoApproveSources`:
 
-<Alert severity="warning">
-<div>
-Do not run `step-agent register` or `step-agent start --login` on a host that Fleet has already synced to Smallstep, and do not add the host through the Smallstep API. The host is already in your inventory, and registering it again fails with `unprocessable entity` or prompts you to register a duplicate device. The agent configuration above is all the host needs.
-</div>
-</Alert>
+```bash
+set +o history
+echo "Authorization: Bearer [your API token]" > api_headers
+set -o history
+
+# Fetch the current policy
+curl -sH @api_headers --request GET \
+  --url https://gateway.smallstep.com/api/device-enrollment-policy \
+  --header 'Accept: application/json' \
+  --header 'x-smallstep-api-version: 2026-05-01' | jq
+
+# Resubmit it with Fleet in autoApproveSources.
+# Adjust both lists to match the policy you fetched.
+curl -sH @api_headers --request PUT \
+  --url https://gateway.smallstep.com/api/device-enrollment-policy \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header 'x-smallstep-api-version: 2026-05-01' \
+  --data '{
+    "allowedSources": ["Smallstep API", "Smallstep Agent", "Fleet"],
+    "autoApproveSources": ["Fleet"],
+    "requireUserBinding": true
+  }' | jq
+```
 
 ## Step 6. Confirmation (Linux)
 
@@ -565,13 +588,34 @@ Add the Smallstep agent MSI as Fleet software so it installs on enrollment:
 2. In the Fleet console, go to **Software**, choose **Add software → Custom package**, and upload the MSI
 3. Scope the install to your Windows hosts
 
-The agent reads the registry values written in Step 3 on startup, attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy).
+On startup, the agent reads the registry values to find the team information, then attests with the endpoint's TPM. Smallstep matches the attestation to the inventory data synced from Fleet.
 
-<Alert severity="warning">
-<div>
-Do not run `step-agent register` or `step-agent start --login` on a host that Fleet has already synced to Smallstep, and do not add the host through the Smallstep API. The host is already in your inventory, and registering it again fails with `unprocessable entity` or prompts you to register a duplicate device. The agent configuration above is all the host needs.
-</div>
-</Alert>
+By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` in your team's device enrollment policy. This setting isn't exposed in the Smallstep console. Use the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy) with an [API token](https://smallstep.com/app/?next=/settings/api/tokens/add) that has the `get-device-enrollment-policy` and `put-device-enrollment-policy` scopes. The `PUT` replaces the whole policy, so fetch the current policy first and resubmit it with `Fleet` added to `autoApproveSources`:
+
+```bash
+set +o history
+echo "Authorization: Bearer [your API token]" > api_headers
+set -o history
+
+# Fetch the current policy
+curl -sH @api_headers --request GET \
+  --url https://gateway.smallstep.com/api/device-enrollment-policy \
+  --header 'Accept: application/json' \
+  --header 'x-smallstep-api-version: 2026-05-01' | jq
+
+# Resubmit it with Fleet in autoApproveSources.
+# Adjust both lists to match the policy you fetched.
+curl -sH @api_headers --request PUT \
+  --url https://gateway.smallstep.com/api/device-enrollment-policy \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header 'x-smallstep-api-version: 2026-05-01' \
+  --data '{
+    "allowedSources": ["Smallstep API", "Smallstep Agent", "Fleet"],
+    "autoApproveSources": ["Fleet"],
+    "requireUserBinding": true
+  }' | jq
+```
 
 ## Step 6. Confirmation (Windows)