TLS CA Certificates API

TLS CA Certificates API Reference

TLS CA Certificates API Examples

Create the bearer_token and store in a file in a secure local directory with 0600 permissions.

TLS CA Certificate Upload

Define the TLS CA certificate parameters and store in /path/to/jsonfile (certificate field shortened for brevity):

{
    "display_name": "Some description",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIFxDCCA6ygAwIBAgIBAjANBgkqhkiG9w0BAQsFADCBsDELMAkGA1UEBhMCVVMx\nETAPBgNV....1NF/BjDZ4wdexw==\n-----END CERTIFICATE-----\n"
}

To include the PEM file content in a JSON string it must be flattened to a single line.

To create a single line representation of a PEM file for the RKVST API, you must replace new lines with the literal string “\n”.

The following unix command could be used:

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' cert-name.pem

Create the CA Certificate:

curl -v -X POST \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/archivist/v1/tlscacertificates

The response is (certificate field shortened for brevity):

{
    "identity": "tlscacertificates/3f5be24f-fd1b-40e2-af35-ec7c14c74d53",
    "display_name": "Some description",
    "certificate": "-----BEGIN CERTIFICATE----- MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT -----END CERTIFICATE-----"
}

TLS CA Certificate Retrieval

TLS CA Certificate records in RKVST are tokenized at creation time and referred to in all API calls and smart contracts throughout the system by a unique identity of the form:

tlscacertificates/12345678-90ab-cdef-1234-567890abcdef

If you do not know the certificate’s identity you can fetch TLS CA Certificate records using other information you do know, such as the certificate’s name.

Fetch all TLS CA Certificates

To fetch all TLS CA certificates records, simply GET the tlscacertificates resource:

curl -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/archivist/v1/tlscacertificates

Fetch specific TLS CA Certificate by Identity

If you know the unique identity of the TLS CA certificate Record simply GET the resource:

curl -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/archivist/v1/tlscacertificates/6a951b62-0a26-4c22-a886-1082297b063b

Fetch TLS CA Certificates by Name

To fetch all TLS CA Certificates with a specific name, GET the tlscacertificates resource and filter on display_name:

curl -g -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/archivist/v1/tlscacertificates?display_name=Acme

Each of these calls returns a list of matching TLS CA Certificate records in the form (certificate field shortened for brevity):

{
    "certificates": [
        {
            "identity": "tlscacertificates/6a951b62-0a26-4c22-a886-1082297b063b",
            "display_name": "Some description",
            "certificate": "-----BEGIN CERTIFICATE----- MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT -----END CERTIFICATE----- "
        },
        {
            "identity": "tlscacertificates/12345678-0a26-4c22-a886-1082297b063b",
            "display_name": "Some other description",
            "certificate": "-----BEGIN CERTIFICATE----- XYZEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT -----END CERTIFICATE----- "
        }
    ]
}

TLS CA Certificate Deletion

To delete a TLS CA Certificate, issue the following request:

curl -v -X DELETE \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    https://app.rkvst.io/archivist/v1/tlscacertificates/47b58286-ff0f-11e9-8f0b-362b9e155667

The response is {}.

Updating a TLS CA Certificate

Define the TLS CA certificates parameters to be changed and store in /path/to/jsonfile:

{
    "display_name": "new description"
}

Update the TLS CA Certificate:

curl -v -X PATCH \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/archivist/v1/tlscacertificates/47b58286-ff0f-11e9-8f0b-362b9e155667

The response is (certificate field shortened for brevity):

{
    "identity": "tlscacertificates/3f5be24f-fd1b-40e2-af35-ec7c14c74d53",
    "display_name": "Some description",
    "certificate": "-----BEGIN CERTIFICATE----- MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT -----END CERTIFICATE-----"
}

TLS CA Certificates OpenAPI Docs

API to manage tls ca certificates.

get  /archivist/v1/tlscacertificates

List TLS CA certificates

Description: Returns a paginated list of TLS CA certificates

{
  "page_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InN0dW50aWR",
  "tlscacertificates": [
    {
      "display_name": "Some description",
      "identity": "tlscacertificates/08838336-c357-460d-902a-3aba9528dd22"
    }
  ]
}
Response ParameterTypeDescription
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
tlscacertificatesarrayDescribes TLS CA certificate in PEM file format.
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to read the TLS CA certificate.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

post  /archivist/v1/tlscacertificates

Upload a TLS CA certificate

Description: This request uploads a TLS CA certificate. The display_name is the friendly name.

{
  "display_name": "Some description",
  "tlscacertificate": "-----BEGIN CERTIFICATE----- MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT -----END CERTIFICATE-----"
}
ParameterTypeDescription
display_namestringCustomer friendly name for the TLS CA certificate.
tlscacertificatestringTLS CA Certificate as string representing the contents of the PEM file

{
  "display_name": "Some description",
  "identity": "tlscacertificates/08838336-c357-460d-902a-3aba9528dd22",
  "tlscacertificate": "-----BEGIN CERTIFICATE----- MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT -----END CERTIFICATE-----"
}
Response ParameterTypeDescription
display_namestringCustomer friendly name for the TLS CA certificate.
identitystringUnique identification for the TLS CA ertificate, Relative Resource Name
tlscacertificatestringTLS CA Certificate as base64 string representing the contents of the PEM file
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
402Returned when the user’s quota of certificates has been reached.
403Returned when the user is not authorized to create a tlscacertificate.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

delete  /archivist/v1/tlscacertificates/{uuid}

Delete a TLS C Acertificate

Description: Delete the identified tLS CA Certificate

ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to delete the TLS CA certificate.
404Returned when the identified laccess policy does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

get  /archivist/v1/tlscacertificates/{uuid}

Get a TLS CA certificate

Description: Returns the identified tlscacertificate

{
  "display_name": "Some description",
  "identity": "tlscacertificates/08838336-c357-460d-902a-3aba9528dd22",
  "tlscacertificate": "-----BEGIN CERTIFICATE----- MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT -----END CERTIFICATE-----"
}
Response ParameterTypeDescription
display_namestringCustomer friendly name for the TLS CA certificate.
identitystringUnique identification for the TLS CA ertificate, Relative Resource Name
tlscacertificatestringTLS CA Certificate as base64 string representing the contents of the PEM file
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to read the TLS CA certificate.
404Returned when the identified TLS CA certificate does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

patch  /archivist/v1/tlscacertificates/{uuid}

Update a TLS CA certificate's details

Description: Perform a full or partial update of the identified TLS CA certificate

{
  "display_name": "Some description",
  "identity": "tlscacertificates/08838336-c357-460d-902a-3aba9528dd22",
  "tlscacertificate": "-----BEGIN CERTIFICATE----- MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT -----END CERTIFICATE-----"
}
Response ParameterTypeDescription
display_namestringCustomer friendly name for the TLS CA certificate.
identitystringUnique identification for the TLS CA ertificate, Relative Resource Name
tlscacertificatestringTLS CA Certificate as base64 string representing the contents of the PEM file
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to update the TLS CA certificate.
404Returned when the identified TLS C Acertificate does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

get  /archivist/v1/tlscacertificates:openapi

Get OpenAPI spec for TLSCACertificates

Description: Get OpenAPI v2.0 spec for TLSCACertificates

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

get  /archivist/v1/tlscacertificates:openapi-ui

Get OpenAPI UI for TLSCACertificates

Description: Get OpenAPI v2.0 UI for TLSCACertificates

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

Edit this page on GitHub