Smallstep API
With the Smallstep API, you can:
- Register new devices in your Smallstep inventory
- Manage your high-level protected resources, such as Wi-Fi or VPN configurations
- Manage low-level resources like X.509 CAs, Attestation authorities, and provisioners
- Manage hosts, host grants, and tags for Smallstep SSH
- 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:
- Long-term token: In your Smallstep settings. Under API Tokens, choose + Add Token. This token has a 10 year validity period and will only be displayed once. Please store it in a safe place!
- Short-term token: On the command line, using the
step
CLI. Thestep 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 a trusted root CA in your Smallstep settings. The trusted root can be a Smallstep CA or an external CA. Only one trusted root CA may be configured.
Output:
[
{
"active": true,
"displayName": "Alice T",
"emails": [
{
"email": "alice@smallstep.com",
"primary": true
}
],
"familyName": "T",
"givenName": "Alice",
"groups": [
{
"id": "a1028765-3d67-44b0-b51b-f7d76727f181",
"name": "admin"
},
{
"id": "eb4b75f0-a341-4dac-a52a-12d90d91b97d",
"name": "super-admin"
}
],
"id": "4510f372-f4ba-4dc7-b6c2-ad22fdaaadb1",
"posixUsers": []
}
]
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.
For each device, use the Save Collection Instance endpoint to create a device.
- For the
collectionSlug
, usedefault
- For Apple devices, the
instanceID
must be the device's serial number. - For TPM 2.0 devices, the
instanceID
must be the TPM Endorsement Key URI, in the formaturn:ek:sha256:ul3sYf6uQ6jVEXAMPLEXoAuHI10U8gTvEJ6bMj95LXI=
. (You can retrieve the EK URI by runningstep agent tpm --fingerprint
on the device.)
For the body of the request,
create a user using the following value
(replacing carl@smallstep.com
with the device owner's email address):
{
"data": {
"name": "Carl's MacBook Pro",
"smallstep:identity": "carl@smallstep.com"
}
}
Once added, the devices will be automatically approved.
You can see the device using the ListCollectionInstances endpoint:
set +o history
echo "Authorization: Bearer [your token]" > api_headers
set -o history
curl -sH @api_headers https://gateway.smallstep.com/api/collections/default/items | jq
Or, in your Smallstep dashboard, you'll see the device listed under Recent Devices.