Device Enrollment Guide

In this guide, we'll talk about different approaches you can take as you build your device inventory in Smallstep.

It's worth restating the overall goal of this process: To build a high-assurance device inventory, so that only your organization's devices can access protected resources.

While many organizations have device inventories in various locations (IT Asset Management systems, device management platforms, etc), these are not usually high-assurance inventories. Smallstep uses hardware identifiers and device attestation to help you develop a high-assurance inventory that can be the foundation for device authentication.

Here's a few ways to bring high-assurance device identifiers into your Smallstep inventory:

You can manually invite users to join your Smallstep team, and they will be able to self-enroll devices using the Smallstep Desktop App or the Smallstep Agent.

By default, administrators must approve a new device before it can access any of your resources. You can change this in Team Settings.

This option requires IdP self-enrollment in Team Settings to be enabled. It is disabled by default.

With IdP self-enrollment enabled, when you connect Smallstep to your identity provider, your users will be able to self-enroll via single sign-on, using the Smallstep Desktop App or the Smallstep Agent.

By default, administrators must approve newly-enrolled devices before they can access any of your resources. You can change this in Team Settings.

You can sync your existing MDM inventories into Smallstep. Once an MDM is synced, you can deploy the Smallstep Agent to your endpoints to enable high-assurance protections.

Devices synced from an MDM inventory are not automatically approved, and they will not be marked as high-assurance until Smallstep receives an attestation from the device.

For a concrete example, see Connect Jamf Pro to Smallstep

You can import devices from any source into Smallstep using our API.

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 with all “device” scopes (put-device, patch-device, etc.).

Use the Add Device 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 endpoint:

set +o history
echo "Authorization: Bearer [your API token]" > api_headers
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

You'll also see new devices in the Smallstep console, under Devices.