OpenAPI Specification
openapi: 3.1.1
info:
contact:
email: support@smallstep.com
name: Smallstep Support
url: https://support.smallstep.com
description: '# Getting Started
First you''ll need to get an API token from the Team Settings page of your [Smallstep dashboard](https://smallstep.com/app).
Then you can try [listing certificates](/operations/list-certificates) for your first API call:
```
set +o history
echo "Authorization: Bearer [your API token]" > api_headers
set -o history
curl -H @api_headers https://gateway.smallstep.com/api/certificates
```
More resources:
* [Terraform Provider](https://github.com/smallstep/terraform-provider-smallstep)
* [Python Client](https://github.com/smallstep/smallstep-python)
'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
summary: Smallstep API
title: Smallstep Authentication Credentials API
version: '2025-01-01'
servers:
- url: https://gateway.smallstep.com/api
security:
- JWT: []
tags:
- description: Manage credentials
name: Credentials
paths:
/credential/{credentialID}:
parameters:
- $ref: '#/components/parameters/requestID'
- $ref: '#/components/parameters/version'
- $ref: '#/components/parameters/accept'
- $ref: '#/components/parameters/credentialID'
delete:
description: 'Delete a credential.
'
operationId: DeleteCredential
responses:
'204':
$ref: '#/components/responses/204'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'500':
$ref: '#/components/responses/500'
security:
- JWT:
- delete-credential
summary: Delete Credential
tags:
- Credentials
get:
description: 'Read a credential.
'
operationId: GetCredential
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/credential'
description: 'The credential.
'
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-Smallstep-Api-Version:
$ref: '#/components/headers/X-Smallstep-Api-Version'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- JWT:
- get-credential
summary: Get Credential
tags:
- Credentials
put:
description: 'Update a credential.
'
operationId: PutCredential
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/credential'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/credential'
description: 'The credential.
'
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-Smallstep-Api-Version:
$ref: '#/components/headers/X-Smallstep-Api-Version'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- JWT:
- put-credential
summary: Put Credential
tags:
- Credentials
/credentials:
parameters:
- $ref: '#/components/parameters/requestID'
- $ref: '#/components/parameters/version'
- $ref: '#/components/parameters/accept'
get:
description: 'List the team''s credentials.
'
operationId: ListCredentials
parameters:
- $ref: '#/components/parameters/pagination'
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/credential'
type: array
description: 'A page of credentials.
'
headers:
X-Next-Cursor:
$ref: '#/components/headers/X-Next-Cursor'
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-Smallstep-Api-Version:
$ref: '#/components/headers/X-Smallstep-Api-Version'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- JWT:
- list-credentials
summary: List Credentials
tags:
- Credentials
post:
description: 'Create a new credential.
'
operationId: PostCredentials
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/credential'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/credential'
description: 'The new credential.
'
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-Smallstep-Api-Version:
$ref: '#/components/headers/X-Smallstep-Api-Version'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'500':
$ref: '#/components/responses/500'
security:
- JWT:
- post-credentials
summary: Create Credential
tags:
- Credentials
components:
schemas:
error:
example:
message: ID must be a valid UUID
properties:
message:
description: A description of the error.
type: string
required:
- message
title: Error
type: object
credentialKey:
description: The attributes of the cryptographic key. Key `type` and `protection` are required unless the `pubFile` is set.
example:
protection: NONE
type: ECDSA_P256
properties:
protection:
description: Whether to use a hardware module to store the private key. If set to `NONE` no hardware module will be used. `HARDWARE_WITH_FALLBACK` can only be used with the key file format `DEFAULT`.
enum:
- NONE
- HARDWARE
- HARDWARE_WITH_FALLBACK
- HARDWARE_ATTESTED
type: string
pubFile:
description: A CSR or SSH public key to use instead of generating one. Cannot be used in conjunction with key type, key protection, key file or key file format.
type: string
type:
description: The key type used. The current default type is `ECDSA_P256` but is not fixed at the time the credential resource is created - new keys generated for this credential in the future may have a different type.
enum:
- DEFAULT
- ECDSA_P256
- ECDSA_P384
- ECDSA_P521
- RSA_2048
- RSA_3072
- RSA_4096
- ED25519
type: string
title: Credential Key
type: object
certificateFieldList:
description: A certificate field that accepts multiple string values, e.g. SANs.
properties:
deviceMetadata:
description: 'Keys in the device''s metadata whose values will populate this certificate field.
In addition to custom metadata keys, the following reserved keys are available: `smallstep:identity`, `Device.ID`, `Device.DisplayName`, `Device.PermanentIdentifier`, `Device.PermanentIdentifierURI`, `Device.Hostname`, `Device.HostURI`, and `Device.Serial`. For SSH certificates, `SSH.Principals` and `SSH.Extensions` are also available. See [deviceMetadata](/schemas/deviceMetadata) for details.
'
items:
type: string
type: array
insecureIncludeRequested:
description: Copy all values from the certificate request into the signed certificate. This allows the client to set arbitrary values for the field.
type: boolean
static:
description: Literal values.
items:
type: string
type: array
title: Certificate Field List
type: object
endpointManagementMode:
description: 'Determines who manages the certificate lifecycle for the workload.
Defaults to `agent` if not set.
- `agent`: The Smallstep Agent manages the certificate lifecycle, including enrollment, renewal, key management, and service reloading.
- `mdm`: An MDM manages the certificate lifecycle. Smallstep describes the desired certificate configuration but does not handle enrollment or renewal.
- `other`: Some other process or workflow manages the certificate lifecycle. Smallstep describes the desired certificate configuration but does not handle enrollment or renewal.
'
enum:
- agent
- mdm
- other
example: agent
title: Endpoint Management Mode
type: string
certificateField:
description: A certificate field that takes a single string value, e.g. Common Name. Static values are used as a fallback when device metadata is not present.
properties:
deviceMetadata:
description: 'A key in the device''s metadata whose value will populate this certificate field. If the key is not present in the device''s metadata, the static value will be used.
In addition to custom metadata keys, the following reserved keys are available: `smallstep:identity`, `Device.ID`, `Device.DisplayName`, `Device.PermanentIdentifier`, `Device.PermanentIdentifierURI`, `Device.Hostname`, `Device.HostURI`, and `Device.Serial`. For SSH certificates, `SSH.KeyID` is also available. See [deviceMetadata](/schemas/deviceMetadata) for details.
'
type: string
static:
description: A literal value.
type: string
title: Certificate Field
type: object
x509ExtendedKeyUsage:
description: A purpose for which a certified public key may be used.
enum:
- serverAuth
- clientAuth
- codeSigning
- emailProtection
- ipsecEndSystem
- ipsecTunnel
- ipsecUser
- timeStamping
- ocspSigning
- microsoftServerGatedCrypto
- netscapeServerGatedCrypto
- microsoftCommercialCodeSigning
- microsoftKernelCodeSigning
- any
title: X.509 Extended Key Usage
type: string
deviceOwnership:
description: 'Whether the device is owned by the user or the company.
This field may be populated with a value derived from data synced from your team''s MDMs.
Setting this value explicitly will mask any MDM-derived value.
'
enum:
- company
- user
type: string
credentialCertificate:
description: Configuration for the certificate of a managed credential.
example:
authorityID: 3c2e1115-49b7-4657-9b0f-301d7111bc6e
duration: 24h0m0s
fields:
commonName:
deviceMetadata: Device.Serial
static: wifi
sans:
deviceMetadata:
- smallstep:identity
type: X509
properties:
authorityID:
description: A UUID identifying the authority that issues certificates for the credential.
type: string
duration:
description: The certificate lifetime. Parsed as a [Golang duration](https://pkg.go.dev/time#ParseDuration).
type: string
fields:
description: Certificate subject fields. See [X.509 Certificate Fields](/schemas/x509Fields) or [SSH Certificate Fields](/schemas/sshFields).
oneOf:
- $ref: '#/components/schemas/x509Fields'
- $ref: '#/components/schemas/sshFields'
namePolicy:
$ref: '#/components/schemas/x509NamePolicy'
type:
enum:
- X509
- SSH_USER
- SSH_HOST
type: string
required:
- type
- authorityID
- fields
title: Credential Certificate
type: object
deviceOS:
description: 'The device operating system.
This field may be populated with a value derived from data synced from your team''s MDMs.
Setting this value explicitly will mask any MDM-derived value.
'
enum:
- Linux
- Windows
- macOS
- iOS
- tvOS
- watchOS
- visionOS
type: string
x509TypedSANs:
description: Explicitly typed subject alternative names. When set, takes precedence over the untyped `sans` field.
properties:
dnsNames:
$ref: '#/components/schemas/certificateFieldList'
emailAddresses:
$ref: '#/components/schemas/certificateFieldList'
ipAddresses:
$ref: '#/components/schemas/certificateFieldList'
uris:
$ref: '#/components/schemas/certificateFieldList'
userPrincipalNames:
$ref: '#/components/schemas/certificateFieldList'
title: X.509 Typed Subject Alternative Names
type: object
credential:
description: A certificate key pair.
properties:
certificate:
$ref: '#/components/schemas/credentialCertificate'
files:
$ref: '#/components/schemas/credentialFiles'
id:
description: A UUID identifying this credential. Read only.
readOnly: true
type: string
key:
$ref: '#/components/schemas/credentialKey'
managementMode:
$ref: '#/components/schemas/endpointManagementMode'
policy:
$ref: '#/components/schemas/policyMatchCriteria'
slug:
type: string
required:
- id
- slug
- certificate
- key
title: Credential
type: object
deviceAssurance:
description: 'The assurance level of the device.
High-assurance devices are those that have a user binding, have been approved, and have performed cryptographic
remote attestation.
'
enum:
- normal
- high
type: string
credentialFiles:
description: Configuration for files that will be written when a managed credential is issued.
example:
crtFile: /etc/db.crt
gid: 999
keyFile: /etc/db.key
keyFormat: PKCS8
mode: 256
rootFile: /etc/ca.crt
uid: 1001
properties:
crtFile:
description: The filepath where the certificate is to be stored.
type: string
gid:
description: GID of the files where the credential is stored.
type: integer
keyFile:
description: The filepath where the key is to be stored.
type: string
keyFormat:
description: The format used to encode the private key. For X.509 keys the default format is PKCS#8. The classic format is PKCS#1 for RSA keys, SEC 1 for ECDSA keys, and PKCS#8 for ED25519 keys. For SSH keys the default format is always the OPENSSH format. When a hardware module is used to store the keys the default will be a JSON representation of the key, except on Linux TSS2 will be used.
enum:
- DEFAULT
- PKCS8
- OPENSSH
- TSS2
- CLASSIC
type: string
mode:
description: Permission bits of the files where the credential is stored.
type: integer
rootFile:
description: The filepath where the root certificate is to be stored.
type: string
uid:
description: UID of the files where the credential is stored.
type: integer
type: object
deviceDiscoverySource:
description: 'The source from which this device was discovered.
'
enum:
- End-User
- Smallstep API
- Smallstep Agent
- Jamf
- Intune
type: string
policyMatchCriteria:
description: Policy to select the devices an account is assigned to. An empty policy indicates an account will be provisioned for all devices.
properties:
assurance:
description: Assurance levels that devices must match.
items:
$ref: '#/components/schemas/deviceAssurance'
type: array
uniqueItems: true
operatingSystem:
description: Operating systems that devices must match.
items:
$ref: '#/components/schemas/deviceOS'
type: array
uniqueItems: true
ownership:
description: Ownership values that devices must match.
items:
$ref: '#/components/schemas/deviceOwnership'
type: array
uniqueItems: true
source:
description: Registration sources that devices must match.
items:
$ref: '#/components/schemas/deviceDiscoverySource'
type: array
uniqueItems: true
tags:
description: Tags that devices must match.
items:
type: string
type: array
type: object
x509NamePolicy:
description: 'Allow- and deny-lists constraining the X.509 names a credential''s
provisioner may issue. When omitted, no name policy is enforced.
On update, omitting this field clears any existing policy.
'
properties:
allow:
$ref: '#/components/schemas/x509Names'
allowWildcardNames:
description: When true, wildcard names like `*.example.com` are permitted.
type: boolean
deny:
$ref: '#/components/schemas/x509Names'
type: object
x509Fields:
description: Populate certificate fields using using static names or device metadata.
properties:
commonName:
$ref: '#/components/schemas/certificateField'
country:
$ref: '#/components/schemas/certificateFieldList'
customExtensions:
description: Arbitrary X.509 extensions to include in the certificate.
items:
$ref: '#/components/schemas/x509CustomExtension'
type: array
extendedKeyUsage:
description: The set of purposes for which the certified public key may be used. Defaults to server and client authentication when omitted.
items:
$ref: '#/components/schemas/x509ExtendedKeyUsage'
type: array
givenName:
$ref: '#/components/schemas/certificateField'
locality:
$ref: '#/components/schemas/certificateFieldList'
organization:
$ref: '#/components/schemas/certificateFieldList'
organizationalUnit:
$ref: '#/components/schemas/certificateFieldList'
postalCode:
$ref: '#/components/schemas/certificateFieldList'
province:
$ref: '#/components/schemas/certificateFieldList'
sans:
$ref: '#/components/schemas/certificateFieldList'
serialNumber:
$ref: '#/components/schemas/certificateField'
streetAddress:
$ref: '#/components/schemas/certificateFieldList'
surname:
$ref: '#/components/schemas/certificateField'
typedSans:
$ref: '#/components/schemas/x509TypedSANs'
title: X.509 Certificate Fields
type: object
x509Names:
description: A set of X.509 name patterns grouped by name type.
properties:
commonNames:
items:
type: string
type: array
dns:
items:
type: string
type: array
emails:
items:
type: string
type: array
ips:
items:
type: string
type: array
uris:
items:
type: string
type: array
type: object
sshFields:
description: Populate certificate fields using static names or device metadata.
properties:
keyId:
$ref: '#/components/schemas/certificateField'
principals:
$ref: '#/components/schemas/certificateFieldList'
title: SSH Certificate Fields
type: object
x509CustomExtension:
description: An arbitrary X.509 certificate extension.
properties:
critical:
description: Whether the extension is marked critical.
type: boolean
oid:
description: The object identifier in dotted notation (e.g. `1.3.6.1.4.1.44947`).
type: string
value:
description: The DER-encoded extension value, base64-encoded.
format: byte
type: string
required:
- oid
- value
title: X.509 Custom Extension
type: object
responses:
'204':
description: The resource has been deleted.
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-Smallstep-Api-Version:
$ref: '#/components/headers/X-Smallstep-Api-Version'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Internal server error
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-Smallstep-Api-Version:
$ref: '#/components/headers/X-Smallstep-Api-Version'
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Unauthorized
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-Smallstep-Api-Version:
$ref: '#/components/headers/X-Smallstep-Api-Version'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Bad request
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-Smallstep-Api-Version:
$ref: '#/components/headers/X-Smallstep-Api-Version'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Forbidden
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-Smallstep-Api-Version:
$ref: '#/components/headers/X-Smallstep-Api-Version'
headers:
X-Next-Cursor:
description: The cursor value to use for the next page of results
example: MTIzNA==
schema:
type: string
X-Request-Id:
description: A request ID provided by the client. If not provided, the server will generate one. Will be reflected in responses.
example: abcdef
schema:
type: string
X-Smallstep-Api-Version:
description: API version to use. Will be reflected in responses.
example: '2025-01-01'
schema:
format: date
type: string
parameters:
version:
description: The version of the Smallstep API. Required unless set in the Accept header.
example: '2025-01-01'
in: header
name: X-Smallstep-Api-Version
required: true
schema:
type: string
credentialID:
description: The UUID of the credential
in: path
name: credentialID
required: true
schema:
type: string
pagination:
description: 'Paginate over a list of objects. Example: `?pagination[first]=30&pagination[after]=MTIzNA==`, which after encoding would be `?pagination%5Bfirst%5D=30&pagination%5Bafter%5D=MTIzNA==`
'
explode: true
in: query
name: pagination
schema:
nullable: true
properties:
after:
description: 'Fetch a page of results other than the first page.
Must be copied from a previously returned X-Next-Cursor header.
'
example: MTIzNA==
nullable: true
type: string
first:
description: 'Limits the number of results returned.
Defaults to 100.
'
example: 30
maximum: 1000
minimum: 1
nullable: true
type: integer
type: object
style: deepObject
requestID:
description: A request ID provided by the client. If not provided, the server will generate one. Will be reflected in responses.
example: abcdef
in: header
name: X-Request-Id
schema:
type: string
accept:
description: The content type the client is willing to accept. Also includes API version.
example: application/vnd.smallstep.v2025-01-01+json
in: header
name: Accept
schema:
type: string
securitySchemes:
JWT:
scheme: bearer
type: http
mtls:
description: Use a client certificate issued by a trusted root to get short-lived bearer tokens with the step CLI.
type: mutualTLS