JSON API Documentation

[prosticoco]

Hello,

Is there any documentation to the JSON API for the step-ca server?

[mmalone]

Hi! Unfortunately, no. We do not have good documentation on the JSON API. It's something we've had on our docs roadmap for a while, but we don't have an ETA yet.

The closest thing to accessible API docs that we have at the moment are the comments in the tinystep Rust library. The library is really well done and the comments describing the API are readable even if you don't know Rust. Check out https://github.com/Bluestone/tinystep/tree/trunk/src.

If you have any specific questions about the API I'm happy to help answer them here.

[maraino]

Another way to figure out the API is looking at the Client implementation used by step and step-ca:

certificates/ca/client.go

Lines 484 to 1051 in 75f24a1

	func (c *Client) Version() (*api.VersionResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/version"})
	retry:
	resp, err := c.client.Get(u.String())
	if err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Version; client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var version api.VersionResponse
	if err := readJSON(resp.Body, &version); err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Version; error reading %s", u)
	}
	return &version, nil
	}
	// Health performs the health request to the CA and returns the
	// api.HealthResponse struct.
	func (c *Client) Health() (*api.HealthResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/health"})
	retry:
	resp, err := c.client.Get(u.String())
	if err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Health; client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var health api.HealthResponse
	if err := readJSON(resp.Body, &health); err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Health; error reading %s", u)
	}
	return &health, nil
	}
	// Root performs the root request to the CA with the given SHA256 and returns
	// the api.RootResponse struct. It uses an insecure client, but it checks the
	// resulting root certificate with the given SHA256, returning an error if they
	// do not match.
	func (c *Client) Root(sha256Sum string) (*api.RootResponse, error) {
	var retried bool
	sha256Sum = strings.ToLower(strings.Replace(sha256Sum, "-", "", -1))
	u := c.endpoint.ResolveReference(&url.URL{Path: "/root/" + sha256Sum})
	retry:
	resp, err := newInsecureClient().Get(u.String())
	if err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Root; client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var root api.RootResponse
	if err := readJSON(resp.Body, &root); err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Root; error reading %s", u)
	}
	// verify the sha256
	sum := sha256.Sum256(root.RootPEM.Raw)
	if sha256Sum != strings.ToLower(hex.EncodeToString(sum[:])) {
	return nil, errs.BadRequest("client.Root; root certificate SHA256 fingerprint do not match")
	}
	return &root, nil
	}
	// Sign performs the sign request to the CA and returns the api.SignResponse
	// struct.
	func (c *Client) Sign(req *api.SignRequest) (*api.SignResponse, error) {
	var retried bool
	body, err := json.Marshal(req)
	if err != nil {
	return nil, errs.Wrap(http.StatusInternalServerError, err, "client.Sign; error marshaling request")
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/sign"})
	retry:
	resp, err := c.client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Sign; client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var sign api.SignResponse
	if err := readJSON(resp.Body, &sign); err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Sign; error reading %s", u)
	}
	// Add tls.ConnectionState:
	// We'll extract the root certificate from the verified chains
	sign.TLS = resp.TLS
	return &sign, nil
	}
	// Renew performs the renew request to the CA and returns the api.SignResponse
	// struct.
	func (c *Client) Renew(tr http.RoundTripper) (*api.SignResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/renew"})
	client := &http.Client{Transport: tr}
	retry:
	resp, err := client.Post(u.String(), "application/json", http.NoBody)
	if err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Renew; client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var sign api.SignResponse
	if err := readJSON(resp.Body, &sign); err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Renew; error reading %s", u)
	}
	return &sign, nil
	}
	// Revoke performs the revoke request to the CA and returns the api.RevokeResponse
	// struct.
	func (c *Client) Revoke(req *api.RevokeRequest, tr http.RoundTripper) (*api.RevokeResponse, error) {
	var retried bool
	body, err := json.Marshal(req)
	if err != nil {
	return nil, errors.Wrap(err, "error marshaling request")
	}
	var client *uaClient
	retry:
	if tr != nil {
	client = newClient(tr)
	} else {
	client = c.client
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/revoke"})
	resp, err := client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errors.Wrapf(err, "client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var revoke api.RevokeResponse
	if err := readJSON(resp.Body, &revoke); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &revoke, nil
	}
	// Provisioners performs the provisioners request to the CA and returns the
	// api.ProvisionersResponse struct with a map of provisioners.
	//
	// ProvisionerOption WithProvisionerCursor and WithProvisionLimit can be used to
	// paginate the provisioners.
	func (c *Client) Provisioners(opts ...ProvisionerOption) (*api.ProvisionersResponse, error) {
	var retried bool
	o := new(provisionerOptions)
	if err := o.apply(opts); err != nil {
	return nil, err
	}
	u := c.endpoint.ResolveReference(&url.URL{
	Path: "/provisioners",
	RawQuery: o.rawQuery(),
	})
	retry:
	resp, err := c.client.Get(u.String())
	if err != nil {
	return nil, errors.Wrapf(err, "client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var provisioners api.ProvisionersResponse
	if err := readJSON(resp.Body, &provisioners); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &provisioners, nil
	}
	// ProvisionerKey performs the request to the CA to get the encrypted key for
	// the given provisioner kid and returns the api.ProvisionerKeyResponse struct
	// with the encrypted key.
	func (c *Client) ProvisionerKey(kid string) (*api.ProvisionerKeyResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/provisioners/" + kid + "/encrypted-key"})
	retry:
	resp, err := c.client.Get(u.String())
	if err != nil {
	return nil, errors.Wrapf(err, "client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var key api.ProvisionerKeyResponse
	if err := readJSON(resp.Body, &key); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &key, nil
	}
	// Roots performs the get roots request to the CA and returns the
	// api.RootsResponse struct.
	func (c *Client) Roots() (*api.RootsResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/roots"})
	retry:
	resp, err := c.client.Get(u.String())
	if err != nil {
	return nil, errors.Wrapf(err, "client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var roots api.RootsResponse
	if err := readJSON(resp.Body, &roots); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &roots, nil
	}
	// Federation performs the get federation request to the CA and returns the
	// api.FederationResponse struct.
	func (c *Client) Federation() (*api.FederationResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/federation"})
	retry:
	resp, err := c.client.Get(u.String())
	if err != nil {
	return nil, errors.Wrapf(err, "client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var federation api.FederationResponse
	if err := readJSON(resp.Body, &federation); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &federation, nil
	}
	// SSHSign performs the POST /ssh/sign request to the CA and returns the
	// api.SSHSignResponse struct.
	func (c *Client) SSHSign(req *api.SSHSignRequest) (*api.SSHSignResponse, error) {
	var retried bool
	body, err := json.Marshal(req)
	if err != nil {
	return nil, errors.Wrap(err, "error marshaling request")
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/sign"})
	retry:
	resp, err := c.client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errors.Wrapf(err, "client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var sign api.SSHSignResponse
	if err := readJSON(resp.Body, &sign); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &sign, nil
	}
	// SSHRenew performs the POST /ssh/renew request to the CA and returns the
	// api.SSHRenewResponse struct.
	func (c *Client) SSHRenew(req *api.SSHRenewRequest) (*api.SSHRenewResponse, error) {
	var retried bool
	body, err := json.Marshal(req)
	if err != nil {
	return nil, errors.Wrap(err, "error marshaling request")
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/renew"})
	retry:
	resp, err := c.client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errors.Wrapf(err, "client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var renew api.SSHRenewResponse
	if err := readJSON(resp.Body, &renew); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &renew, nil
	}
	// SSHRekey performs the POST /ssh/rekey request to the CA and returns the
	// api.SSHRekeyResponse struct.
	func (c *Client) SSHRekey(req *api.SSHRekeyRequest) (*api.SSHRekeyResponse, error) {
	var retried bool
	body, err := json.Marshal(req)
	if err != nil {
	return nil, errors.Wrap(err, "error marshaling request")
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/rekey"})
	retry:
	resp, err := c.client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errors.Wrapf(err, "client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var rekey api.SSHRekeyResponse
	if err := readJSON(resp.Body, &rekey); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &rekey, nil
	}
	// SSHRevoke performs the POST /ssh/revoke request to the CA and returns the
	// api.SSHRevokeResponse struct.
	func (c *Client) SSHRevoke(req *api.SSHRevokeRequest) (*api.SSHRevokeResponse, error) {
	var retried bool
	body, err := json.Marshal(req)
	if err != nil {
	return nil, errors.Wrap(err, "error marshaling request")
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/revoke"})
	retry:
	resp, err := c.client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errors.Wrapf(err, "client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var revoke api.SSHRevokeResponse
	if err := readJSON(resp.Body, &revoke); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &revoke, nil
	}
	// SSHRoots performs the GET /ssh/roots request to the CA and returns the
	// api.SSHRootsResponse struct.
	func (c *Client) SSHRoots() (*api.SSHRootsResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/roots"})
	retry:
	resp, err := c.client.Get(u.String())
	if err != nil {
	return nil, errors.Wrapf(err, "client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var keys api.SSHRootsResponse
	if err := readJSON(resp.Body, &keys); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &keys, nil
	}
	// SSHFederation performs the get /ssh/federation request to the CA and returns
	// the api.SSHRootsResponse struct.
	func (c *Client) SSHFederation() (*api.SSHRootsResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/federation"})
	retry:
	resp, err := c.client.Get(u.String())
	if err != nil {
	return nil, errors.Wrapf(err, "client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var keys api.SSHRootsResponse
	if err := readJSON(resp.Body, &keys); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &keys, nil
	}
	// SSHConfig performs the POST /ssh/config request to the CA to get the ssh
	// configuration templates.
	func (c *Client) SSHConfig(req *api.SSHConfigRequest) (*api.SSHConfigResponse, error) {
	var retried bool
	body, err := json.Marshal(req)
	if err != nil {
	return nil, errors.Wrap(err, "error marshaling request")
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/config"})
	retry:
	resp, err := c.client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errors.Wrapf(err, "client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var config api.SSHConfigResponse
	if err := readJSON(resp.Body, &config); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &config, nil
	}
	// SSHCheckHost performs the POST /ssh/check-host request to the CA with the
	// given principal.
	func (c *Client) SSHCheckHost(principal string, token string) (*api.SSHCheckPrincipalResponse, error) {
	var retried bool
	body, err := json.Marshal(&api.SSHCheckPrincipalRequest{
	Type: provisioner.SSHHostCert,
	Principal: principal,
	Token: token,
	})
	if err != nil {
	return nil, errs.Wrap(http.StatusInternalServerError, err, "error marshaling request",
	errs.WithMessage("Failed to marshal the check-host request"))
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/check-host"})
	retry:
	resp, err := c.client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client POST %s failed",
	[]interface{}{u, errs.WithMessage("Failed to perform POST request to %s", u)}...)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, errs.StatusCodeError(resp.StatusCode, readError(resp.Body))
	}
	var check api.SSHCheckPrincipalResponse
	if err := readJSON(resp.Body, &check); err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "error reading %s response",
	[]interface{}{u, errs.WithMessage("Failed to parse response from /ssh/check-host endpoint")})
	}
	return &check, nil
	}
	// SSHGetHosts performs the GET /ssh/get-hosts request to the CA.
	func (c *Client) SSHGetHosts() (*api.SSHGetHostsResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/hosts"})
	retry:
	resp, err := c.client.Get(u.String())
	if err != nil {
	return nil, errors.Wrapf(err, "client GET %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var hosts api.SSHGetHostsResponse
	if err := readJSON(resp.Body, &hosts); err != nil {
	return nil, errors.Wrapf(err, "error reading %s", u)
	}
	return &hosts, nil
	}
	// SSHBastion performs the POST /ssh/bastion request to the CA.
	func (c *Client) SSHBastion(req *api.SSHBastionRequest) (*api.SSHBastionResponse, error) {
	var retried bool
	body, err := json.Marshal(req)
	if err != nil {
	return nil, errors.Wrap(err, "client.SSHBastion; error marshaling request")
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/ssh/bastion"})
	retry:
	resp, err := c.client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errors.Wrapf(err, "client.SSHBastion; client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var bastion api.SSHBastionResponse
	if err := readJSON(resp.Body, &bastion); err != nil {
	return nil, errors.Wrapf(err, "client.SSHBastion; error reading %s", u)
	}
	return &bastion, nil
	}
	// RootFingerprint is a helper method that returns the current root fingerprint.
	// It does an health connection and gets the fingerprint from the TLS verified
	// chains.
	func (c *Client) RootFingerprint() (string, error) {
	u := c.endpoint.ResolveReference(&url.URL{Path: "/health"})
	resp, err := c.client.Get(u.String())
	if err != nil {
	return "", errors.Wrapf(err, "client GET %s failed", u)
	}
	if resp.TLS == nil || len(resp.TLS.VerifiedChains) == 0 {
	return "", errors.New("missing verified chains")
	}
	lastChain := resp.TLS.VerifiedChains[len(resp.TLS.VerifiedChains)-1]
	if len(lastChain) == 0 {
	return "", errors.New("missing verified chains")
	}
	return x509util.Fingerprint(lastChain[len(lastChain)-1]), nil
	}