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 Setup and Usage

👉 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. 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 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.

API Clients

Getting Started

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": []
  }
]

Example: Add devices via the API

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.

Example: I have a list of device identifiers

For each device, use the Save Collection Instance endpoint to create a device.

For the collectionSlug, use default
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 format urn:ek:sha256:ul3sYf6uQ6jVEXAMPLEXoAuHI10U8gTvEJ6bMj95LXI=. (You can retrieve the EK URI by running step 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