Merge pull request #279 from smallstep/carl/api-docs

Smallstep API single-page doc

manifest.json

@@ -34,6 +34,10 @@
             {
               "title": "Getting Started",
               "path": "/platform/getting-started.mdx"
+            },
+            {
+              "title": "Smallstep API",
+              "path": "/platform/smallstep-api.mdx"
             }
           ]
         },

platform/getting-started.mdx

@@ -16,6 +16,6 @@ Your client machines can use the Step CLI for utility tasks, like bootstrapping
 
 ## Smallstep API
 
-[The Smallstep API](https://gateway.smallstep.com/) gives you full programmatic access to the functionality of the Smallstep platform. You can register workloads or devices, create collections, and configure the Smallstep agent all through the API without needing to use the platform UI.
+[The Smallstep API](smallstep-api.mdx) gives you full programmatic access to the functionality of the Smallstep platform. You can register workloads or devices, create collections, and configure the Smallstep agent all through the API without needing to use the platform UI.
 
 We also have a Smallstep Terraform Provider, which sits on top of the API to provision and manage your Smallstep resources, and the Smallstep Ansible Collection makes it easy to deploy the agent to your infrastructure.

platform/how-it-works.mdx

@@ -14,7 +14,7 @@ We don’t do this by trying to become your identity provider, user or asset dat
 
 All devices registering with your Smallstep team are first added to your device trust zone (or device PKI). To register, devices can leverage existing roots of trust: a Trusted Platform Module (TPM) in Linux, an Instance Identity document or attestation token from any cloud provider, or an attestation certificate.
 
-We rely on hardware roots of trust wherever possible, so that *only* your devices can register with Smallstep. The Smallstep [API](https://gateway.smallstep.com/) and [IaC integrations](https://github.com/smallstep/ansible-collection-agent/) make it easy to sync your device inventory to Smallstep. The device trust zone is a privileged trust zone. It offers an authentication factor, and it becomes a foundation for creating other trust zones.
+We rely on hardware roots of trust wherever possible, so that *only* your devices can register with Smallstep. The Smallstep [API](smallstep-api.mdx) and IaC integrations make it easy to sync your device inventory to Smallstep. The device trust zone is a privileged trust zone. It offers an authentication factor, and it becomes a foundation for creating other trust zones.
 
 ## People and Workload Trust Zones
 
@@ -70,4 +70,4 @@ For walk through guides for other workloads, see [Getting Started](./getting-sta
 - GitHub Actions
 - Any custom app that uses TLS
 
-Don’t see your workload type listed? [Ask us](https://support.smallstep.com/kb-tickets/new).
+Don’t see your workload type listed? [Ask us](https://support.smallstep.com/kb-tickets/new).

platform/smallstep-api.mdx

@@ -0,0 +1,110 @@
+---
+title: Smallstep API
+html_title: Smallstep API
+description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, priviledged access management, passwordless authentication, and much more.
+---
+
+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](https://www.openapis.org/), with JSON requests and responses.
+
+### TL;DR Links
+
+- Get an API token in your [Smallstep dashboard](https://smallstep.com/app). In the bottom-left **⋮** menu, go to **Settings**. Under **API Tokens**, choose **+ Add Token.**
+- Visit the [Smallstep API Specification and Playground](https://gateway.smallstep.com).
+- [Smallstep Terraform Provider](https://github.com/smallstep/terraform-provider-smallstep) ([Documentation](https://registry.terraform.io/providers/smallstep/smallstep/latest/docs))
+- [Smallstep API Python Client](https://github.com/smallstep/smallstep-python)
+
+### Getting Started
+
+You’ll need an API token to get started. You can create one by [signing into the Smallstep dashboard](https://smallstep.com/app/). 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:
+
+```bash
+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:
+
+```bash
+[
+  {
+    "active": true,
+    "displayName": "Alice T",
+    "emails": [
+      {
+        "email": "[email protected]",
+        "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](https://gateway.smallstep.com/operations/PutDeviceCollection).
+
+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](https://gateway.smallstep.com/operations/PutWorkload).
+
+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](https://gateway.smallstep.com/operations/PutCollectionInstance).
+
+Each device’s `instanceID` should be set according to the device type:
+
+- For AWS EC2 instances, use the EC2 instance ID (eg. [`i-0d460b88a96dfdd08`](https://us-east-2.console.aws.amazon.com/ec2/home?region=us-east-2#InstanceDetails:instanceId=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](https://www.notion.so/Bootstrap-device-trust-using-device-attestation-with-Smallstep-f1dc366a17bf4e628520aabfa18b5b80?pvs=21) 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](https://www.notion.so/Smallstep-agent-quickstart-124d5474fdf34ebab4f86b4bb6b0aaad?pvs=21) for details.