smallstep_full_white

Smallstep API

With the Smallstep API, you can:

  • Register VMs with Smallstep as you spin them up, for instant trust bootstrapping
  • Integrate certificate lifecycle management into your Terraform and Ansible definitions
  • Programmatically manage CAs, SSH grants and tags, and more!

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

Getting Started

You’ll need an API token to get started. You can create one by signing into the Smallstep dashboard. In the bottom-left ⋮ menu, go to Settings. Under API Tokens, choose + Add Token.

Your API token has a 10 year validity period and will only be displayed once. Please store it in a safe place!

Once you have a token, try your first API call:

set +o history
echo "Authorization: Bearer [your token]" > api_headers
set -o history
curl -sH @api_headers https://gateway.smallstep.com/api/users | jq

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

Configure Devices and Workloads via the API

Here’s the most common workflow for using the Smallstepi API, either directly or via the Terraform or Ansible integrations:

1. Create a device collection.

Set the device type according to your deployment. Note that each device type is going to have its own deviceTypeConfiguration as well. For example, an Azure VM device will require you to set your Azure tenant ID, for access control.

You’ll register your individual devices in step 3.

2. Add workloads.

This is where you set up your workload configuration. You can specify things like certificate SANs and duration, certificate and key file ownership and permissions, reload options for the workload, and so on.

A single workload can be associated with multiple devices.

Have three HAProxy hosts in front of a fleet of internal.example.com web servers? That’s one workload.

Have a PostgreSQL server with several hot standby servers? That’s one workload.

Have an etcd cluster comprised of three hosts? That’s one workload.

On this endpoint, you can use the deviceMetadataKeySANs property to dynamically map certificate SANs for each device that’s running a workload. Or, statically assign SANs for every certificate in the workload, using staticSANs.

3. Add devices to collection.

Each device’s instanceID should be set according to the device type:

  • For AWS EC2 instances, use the EC2 instance ID (eg. i-0d460b88a96dfdd08)
  • For Azure VMs, use the managed identity principal object ID
  • For Compute Engine VMs, use the instance ID (eg. 16979701088048819)
  • For TPM devices, use the TPM’s EKpub URI (see our TPM documentation for details)

Use the data field to store any relevant instance metadata, such as:

  • an instance’s region, name, or role(s)
  • DNS names (these can be mapped to a SANs using deviceMetadataKeySANs, above)

4. Install the Smallstep agent on each device.

The agent will only need your team name and fingerprint for bootstrapping.

See Smallstep Agent Quickstart for details.