Smallstep API

With the Smallstep API, you can manage:

• Devices in your Smallstep inventory
• High-level protected resources, such as Wi-Fi or VPN configurations
• Lower-level PKI resources like X.509 CAs and provisioners
• Smallstep SSH hosts, host grants, and tags (use the 2023-11-01 API version for this)
• And more!

The Smallstep API is OpenAPI conformant, with JSON requests and responses.

👉 Smallstep API Specification and Playground

You can get an API token in two ways:

• Smallstep UI: Add a token in Smallstep settings. You can choose the validity period and scopes here.
• Command Line: On the command line, using the step CLI. The step api token create command accepts a client certificate and private key to authenticate with Smallstep and issue a temporary API token with a 1 hour validity period. To use this option, you must configure one or more trusted root CAs in the Smallstep UI. Trusted roots can be Smallstep CAs or external CAs.

• Smallstep API Python Client
• Smallstep Terraform Provider (Documentation)

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.

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

Or, in your Smallstep dashboard, you'll see the device listed under Recent Devices.