smallstep_full_white

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:

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

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