Skip to content

Instantly share code, notes, and snippets.

@mcarbonneaux

mcarbonneaux/smallstep-api.swagger

Last active May 29, 2025 13:42
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save mcarbonneaux/2b92761b13e17e46c20e34e9de5771a9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save mcarbonneaux/2b92761b13e17e46c20e34e9de5771a9 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
smallstep-api.swagger
openapi: 3.0.3
info:
title: Smallstep Certificates API
description: |
REST API for Smallstep Certificates - A private certificate authority (X.509 & SSH) & ACME server
for secure automated certificate management.
This API allows you to:
- Sign certificate requests
- Revoke certificates
- Renew certificates
- Get CA roots and federation
- Manage SSH certificates
Authentication is typically done using JWT tokens or provisioner-specific authentication methods.
version: 1.0.0
contact:
name: Smallstep
url: https://github.com/smallstep/certificates
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://localhost:9000
description: Default step-ca server
- url: https://ca.example.com
description: Production CA server
security:
- BearerAuth: []
paths:
/1.0/sign:
post:
summary: Sign a certificate signing request
description: |
Signs a Certificate Signing Request (CSR) and returns a signed certificate.
Requires proper authentication via JWT token or other provisioner methods.
operationId: signCertificate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SignRequest'
example:
csr: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0..."
ott: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
notAfter: "2024-12-31T23:59:59Z"
notBefore: "2024-01-01T00:00:00Z"
responses:
'200':
description: Certificate successfully signed
content:
application/json:
schema:
$ref: '#/components/schemas/SignResponse'
example:
cert: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
certChain: ["LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."]
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalError'
/1.0/renew:
post:
summary: Renew a certificate
description: |
Renews an existing certificate. The request must include the current certificate
and proper authentication.
operationId: renewCertificate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RenewRequest'
example:
cert: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
responses:
'200':
description: Certificate successfully renewed
content:
application/json:
schema:
$ref: '#/components/schemas/SignResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/1.0/revoke:
post:
summary: Revoke a certificate
description: |
Revokes a certificate using either the certificate itself or its serial number.
Requires proper authentication and authorization.
operationId: revokeCertificate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeRequest'
example:
cert: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
reason: "cessationOfOperation"
reasonCode: 5
ott: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
responses:
'200':
description: Certificate successfully revoked
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeResponse'
example:
status: "ok"
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalError'
/1.0/roots:
get:
summary: Get CA root certificates
description: |
Returns the root certificates of the Certificate Authority.
This endpoint is typically public and doesn't require authentication.
operationId: getRoots
responses:
'200':
description: Root certificates retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RootsResponse'
example:
roots: ["LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."]
'500':
$ref: '#/components/responses/InternalError'
/1.0/federation:
get:
summary: Get federation certificates
description: |
Returns the federated root certificates that this CA trusts.
Used for cross-CA certificate validation.
operationId: getFederation
responses:
'200':
description: Federation certificates retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FederationResponse'
example:
federated: ["LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."]
'500':
$ref: '#/components/responses/InternalError'
/1.0/health:
get:
summary: Health check
description: Returns the health status of the CA server
operationId: getHealth
responses:
'200':
description: Server is healthy
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
example:
status: "ok"
'500':
$ref: '#/components/responses/InternalError'
/1.0/version:
get:
summary: Get version information
description: Returns version information about the CA server
operationId: getVersion
responses:
'200':
description: Version information retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/VersionResponse'
example:
version: "0.25.0"
require_client_authentication: true
/1.0/ssh/sign:
post:
summary: Sign SSH certificate
description: |
Signs an SSH certificate request and returns a signed SSH certificate.
Used for SSH certificate-based authentication.
operationId: signSSHCertificate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SSHSignRequest'
example:
ott: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
publicKey: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB..."
certType: "user"
keyID: "[email protected]"
principals: ["user", "admin"]
validAfter: "2024-01-01T00:00:00Z"
validBefore: "2024-12-31T23:59:59Z"
responses:
'200':
description: SSH certificate successfully signed
content:
application/json:
schema:
$ref: '#/components/schemas/SSHSignResponse'
example:
certificate: "[email protected] AAAAHHNzaC1..."
identityID: "[email protected]"
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalError'
/1.0/ssh/renew:
post:
summary: Renew SSH certificate
description: Renews an existing SSH certificate
operationId: renewSSHCertificate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SSHRenewRequest'
example:
ott: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
responses:
'200':
description: SSH certificate successfully renewed
content:
application/json:
schema:
$ref: '#/components/schemas/SSHSignResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/1.0/ssh/revoke:
post:
summary: Revoke SSH certificate
description: Revokes an SSH certificate
operationId: revokeSSHCertificate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SSHRevokeRequest'
example:
ott: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
serial: "1234567890"
responses:
'200':
description: SSH certificate successfully revoked
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/1.0/ssh/roots:
get:
summary: Get SSH CA public keys
description: Returns the SSH CA public keys for host and user certificates
operationId: getSSHRoots
responses:
'200':
description: SSH roots retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SSHRootsResponse'
example:
hostKey: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB..."
userKey: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB..."
'500':
$ref: '#/components/responses/InternalError'
/1.0/ssh/config:
post:
summary: Get SSH client configuration
description: Returns SSH client configuration for the given host
operationId: getSSHConfig
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SSHConfigRequest'
example:
type: "host"
hostname: "example.com"
responses:
'200':
description: SSH configuration retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SSHConfigResponse'
example:
config: "Host example.com\n HostKeyAlgorithms..."
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalError'
/provisioners:
get:
summary: Get all provisioners
description: |
Returns a list of all configured provisioners on the CA.
This endpoint is typically used to discover available provisioners and their capabilities.
operationId: getProvisioners
parameters:
- name: cursor
in: query
description: Cursor for pagination
required: false
schema:
type: string
- name: limit
in: query
description: Maximum number of provisioners to return
required: false
schema:
type: integer
default: 20
maximum: 100
responses:
'200':
description: Provisioners retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProvisionersResponse'
example:
provisioners:
- id: "acme"
name: "ACME"
type: "ACME"
encryptedKey: ""
claims:
minTLSCertDuration: "5m"
maxTLSCertDuration: "24h"
defaultTLSCertDuration: "24h"
- id: "jwk-provisioner"
name: "JWK"
type: "JWK"
key:
kty: "EC"
crv: "P-256"
x: "..."
y: "..."
encryptedKey: "..."
nextCursor: ""
'500':
$ref: '#/components/responses/InternalError'
/provisioners/{provisionerID}:
get:
summary: Get provisioner by ID
description: Returns detailed information about a specific provisioner
operationId: getProvisionerByID
parameters:
- name: provisionerID
in: path
required: true
description: ID of the provisioner
schema:
type: string
example: "acme"
responses:
'200':
description: Provisioner retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Provisioner'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/root/{sha}:
get:
summary: Get root certificate by SHA fingerprint
description: |
Returns a specific root certificate identified by its SHA fingerprint.
This is useful when you know the specific root certificate you need.
operationId: getRootBySHA
parameters:
- name: sha
in: path
required: true
description: SHA fingerprint of the root certificate
schema:
type: string
example: "d9d020ce70ce5aab2e9fcae49c2a9f71c3b1e4a0"
responses:
'200':
description: Root certificate retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RootResponse'
example:
root: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/1.0/rekey:
post:
summary: Rekey a certificate
description: |
Generates a new certificate with a new public key while maintaining the same identity.
This is useful for key rotation scenarios.
operationId: rekeyCertificate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RekeyRequest'
example:
csr: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0..."
cert: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
responses:
'200':
description: Certificate successfully rekeyed
content:
application/json:
schema:
$ref: '#/components/schemas/SignResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/1.0/ssh/rekey:
post:
summary: Rekey SSH certificate
description: Generates a new SSH certificate with a new public key
operationId: rekeySSHCertificate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SSHRekeyRequest'
example:
ott: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
publicKey: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB..."
cert: "[email protected] AAAAHHNzaC1..."
responses:
'200':
description: SSH certificate successfully rekeyed
content:
application/json:
schema:
$ref: '#/components/schemas/SSHSignResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/1.0/ssh/check-host:
post:
summary: Check SSH host certificate
description: Validates an SSH host certificate against the CA
operationId: checkSSHHost
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SSHCheckHostRequest'
example:
hostname: "example.com"
certificate: "[email protected] AAAAHHNzaC1..."
responses:
'200':
description: SSH host certificate is valid
content:
application/json:
schema:
$ref: '#/components/schemas/SSHCheckHostResponse'
example:
valid: true
principals: ["example.com", "*.example.com"]
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalError'
/1.0/ssh/bastion:
post:
summary: Get SSH bastion configuration
description: Returns SSH bastion configuration for secure access
operationId: getSSHBastion
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SSHBastionRequest'
example:
hostname: "bastion.example.com"
user: "admin"
responses:
'200':
description: SSH bastion configuration retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SSHBastionResponse'
example:
hostname: "bastion.example.com"
user: "admin"
port: 22
command: "ssh -o UserKnownHostsFile=/dev/null..."
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalError'
/1.0/crl:
get:
summary: Get Certificate Revocation List
description: |
Returns the Certificate Revocation List (CRL) containing all revoked certificates.
This is used by clients to check if a certificate has been revoked.
operationId: getCRL
responses:
'200':
description: CRL retrieved successfully
content:
application/pkix-crl:
schema:
type: string
format: binary
description: DER-encoded Certificate Revocation List
application/json:
schema:
$ref: '#/components/schemas/CRLResponse'
example:
crl: "LS0tLS1CRUdJTiBYNTA5IENSTC0tLS0t..."
'500':
$ref: '#/components/responses/InternalError'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token for authentication (One-Time Token)
schemas:
SignRequest:
type: object
required:
- csr
- ott
properties:
csr:
type: string
description: Base64 encoded Certificate Signing Request (CSR)
example: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0..."
ott:
type: string
description: One-Time Token (JWT) for authentication
example: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
notAfter:
type: string
format: date-time
description: Certificate expiration time
example: "2024-12-31T23:59:59Z"
notBefore:
type: string
format: date-time
description: Certificate valid from time
example: "2024-01-01T00:00:00Z"
SignResponse:
type: object
properties:
cert:
type: string
description: Base64 encoded signed certificate
example: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
certChain:
type: array
items:
type: string
description: Certificate chain including intermediate certificates
example: ["LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."]
RenewRequest:
type: object
required:
- cert
properties:
cert:
type: string
description: Base64 encoded certificate to renew
example: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
RevokeRequest:
type: object
properties:
cert:
type: string
description: Base64 encoded certificate to revoke
example: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
serial:
type: string
description: Serial number of certificate to revoke (alternative to cert)
example: "123456789"
ott:
type: string
description: One-Time Token for authentication
example: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
reason:
type: string
description: Reason for revocation
enum:
- unspecified
- keyCompromise
- cACompromise
- affiliationChanged
- superseded
- cessationOfOperation
- certificateHold
- removeFromCRL
- privilegeWithdrawn
- aACompromise
example: "cessationOfOperation"
reasonCode:
type: integer
description: Numeric reason code for revocation
example: 5
RevokeResponse:
type: object
properties:
status:
type: string
description: Status of the revocation operation
example: "ok"
RootsResponse:
type: object
properties:
roots:
type: array
items:
type: string
description: Array of Base64 encoded root certificates
example: ["LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."]
FederationResponse:
type: object
properties:
federated:
type: array
items:
type: string
description: Array of Base64 encoded federated root certificates
example: ["LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."]
HealthResponse:
type: object
properties:
status:
type: string
description: Health status of the server
example: "ok"
VersionResponse:
type: object
properties:
version:
type: string
description: Version of the step-ca server
example: "0.25.0"
require_client_authentication:
type: boolean
description: Whether client authentication is required
example: true
SSHSignRequest:
type: object
required:
- ott
- publicKey
- certType
properties:
ott:
type: string
description: One-Time Token for authentication
example: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
publicKey:
type: string
description: SSH public key to be signed
example: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB..."
certType:
type: string
enum: [user, host]
description: Type of SSH certificate
example: "user"
keyID:
type: string
description: Key identifier for the certificate
example: "[email protected]"
principals:
type: array
items:
type: string
description: List of principals (usernames/hostnames) for the certificate
example: ["user", "admin"]
validAfter:
type: string
format: date-time
description: Certificate valid from time
example: "2024-01-01T00:00:00Z"
validBefore:
type: string
format: date-time
description: Certificate valid until time
example: "2024-12-31T23:59:59Z"
SSHSignResponse:
type: object
properties:
certificate:
type: string
description: Signed SSH certificate
example: "[email protected] AAAAHHNzaC1..."
identityID:
type: string
description: Identity ID of the certificate
example: "[email protected]"
SSHRenewRequest:
type: object
required:
- ott
properties:
ott:
type: string
description: One-Time Token for authentication
example: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
SSHRevokeRequest:
type: object
required:
- ott
- serial
properties:
ott:
type: string
description: One-Time Token for authentication
example: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
serial:
type: string
description: Serial number of SSH certificate to revoke
example: "1234567890"
SSHRootsResponse:
type: object
properties:
hostKey:
type: string
description: SSH CA public key for host certificates
example: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB..."
userKey:
type: string
description: SSH CA public key for user certificates
example: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB..."
SSHConfigRequest:
type: object
required:
- type
properties:
type:
type: string
enum: [host, user]
description: Type of SSH configuration
example: "host"
hostname:
type: string
description: Hostname for host configuration
example: "example.com"
SSHConfigResponse:
type: object
properties:
config:
type: string
description: SSH client configuration
example: "Host example.com\n HostKeyAlgorithms..."
ProvisionersResponse:
type: object
properties:
provisioners:
type: array
items:
$ref: '#/components/schemas/Provisioner'
description: List of provisioners
nextCursor:
type: string
description: Cursor for next page of results
example: ""
Provisioner:
type: object
properties:
id:
type: string
description: Unique identifier for the provisioner
example: "acme"
name:
type: string
description: Human-readable name of the provisioner
example: "ACME"
type:
type: string
enum: [JWK, OIDC, ACME, AWS, GCP, Azure, SCEP, Nebula, K8SSA]
description: Type of provisioner
example: "ACME"
key:
type: object
description: Public key for JWK provisioners
properties:
kty:
type: string
example: "EC"
crv:
type: string
example: "P-256"
x:
type: string
example: "..."
y:
type: string
example: "..."
encryptedKey:
type: string
description: Encrypted private key (for some provisioner types)
example: "..."
clientID:
type: string
description: Client ID for OIDC provisioners
example: "client-id"
clientSecret:
type: string
description: Client secret for OIDC provisioners (usually not returned)
example: "[REDACTED]"
configurationEndpoint:
type: string
description: OIDC configuration endpoint
example: "https://accounts.google.com/.well-known/openid_configuration"
admins:
type: array
items:
type: string
description: List of admin emails for OIDC provisioners
example: ["[email protected]"]
domains:
type: array
items:
type: string
description: Allowed domains for OIDC provisioners
example: ["example.com"]
claims:
$ref: '#/components/schemas/Claims'
options:
type: object
description: Additional provisioner-specific options
additionalProperties: true
Claims:
type: object
description: Certificate claims and constraints
properties:
minTLSCertDuration:
type: string
description: Minimum TLS certificate duration
example: "5m"
maxTLSCertDuration:
type: string
description: Maximum TLS certificate duration
example: "24h"
defaultTLSCertDuration:
type: string
description: Default TLS certificate duration
example: "24h"
minUserSSHCertDuration:
type: string
description: Minimum SSH user certificate duration
example: "5m"
maxUserSSHCertDuration:
type: string
description: Maximum SSH user certificate duration
example: "24h"
defaultUserSSHCertDuration:
type: string
description: Default SSH user certificate duration
example: "16h"
minHostSSHCertDuration:
type: string
description: Minimum SSH host certificate duration
example: "5m"
maxHostSSHCertDuration:
type: string
description: Maximum SSH host certificate duration
example: "720h"
defaultHostSSHCertDuration:
type: string
description: Default SSH host certificate duration
example: "720h"
enableSSHCA:
type: boolean
description: Whether SSH CA is enabled
example: true
disableRenewal:
type: boolean
description: Whether certificate renewal is disabled
example: false
allowRenewalAfterExpiry:
type: boolean
description: Whether renewal is allowed after certificate expiry
example: false
RootResponse:
type: object
properties:
root:
type: string
description: Base64 encoded root certificate
example: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
RekeyRequest:
type: object
required:
- csr
- cert
properties:
csr:
type: string
description: Base64 encoded Certificate Signing Request with new public key
example: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0..."
cert:
type: string
description: Base64 encoded current certificate to be rekeyed
example: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
SSHRekeyRequest:
type: object
required:
- ott
- publicKey
- cert
properties:
ott:
type: string
description: One-Time Token for authentication
example: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
publicKey:
type: string
description: New SSH public key
example: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB..."
cert:
type: string
description: Current SSH certificate to be rekeyed
example: "[email protected] AAAAHHNzaC1..."
SSHCheckHostRequest:
type: object
required:
- hostname
- certificate
properties:
hostname:
type: string
description: Hostname to validate against
example: "example.com"
certificate:
type: string
description: SSH host certificate to validate
example: "[email protected] AAAAHHNzaC1..."
SSHCheckHostResponse:
type: object
properties:
valid:
type: boolean
description: Whether the certificate is valid for the hostname
example: true
principals:
type: array
items:
type: string
description: Valid principals from the certificate
example: ["example.com", "*.example.com"]
SSHBastionRequest:
type: object
required:
- hostname
properties:
hostname:
type: string
description: Bastion hostname
example: "bastion.example.com"
user:
type: string
description: SSH user
example: "admin"
SSHBastionResponse:
type: object
properties:
hostname:
type: string
description: Bastion hostname
example: "bastion.example.com"
user:
type: string
description: SSH user
example: "admin"
port:
type: integer
description: SSH port
example: 22
command:
type: string
description: SSH command to connect through bastion
example: "ssh -o UserKnownHostsFile=/dev/null..."
CRLResponse:
type: object
properties:
crl:
type: string
description: Base64 encoded Certificate Revocation List
example: "LS0tLS1CRUdJTiBYNTA5IENSTC0tLS0t..."
Error:
type: object
properties:
status:
type: integer
description: HTTP status code
example: 400
message:
type: string
description: Error message
example: "Bad request"
detail:
type: string
description: Detailed error information
example: "Invalid certificate signing request format"
responses:
BadRequest:
description: Bad request - invalid input parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 400
message: "Bad request"
detail: "Invalid certificate signing request format"
Unauthorized:
description: Unauthorized - invalid or missing authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 401
message: "Unauthorized"
detail: "Invalid or expired JWT token"
Forbidden:
description: Forbidden - insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 403
message: "Forbidden"
detail: "Insufficient permissions for this operation"
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 404
message: "Not found"
detail: "The requested resource was not found"
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 500
message: "Internal server error"
detail: "Failed to process certificate request"
tags:
- name: Certificates
description: X.509 certificate operations
- name: SSH
description: SSH certificate operations
- name: CA Management
description: Certificate Authority management endpoints
- name: System
description: System health and information endpoints
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment