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 Parameter Type Description
next_page_token string Token to retrieve the next page of results or empty if there are none.
tlscacertificates array Describes TLS CA certificate in PEM file format.
Responses Description
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.
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-----"
}
Parameter Type Description
display_name string Customer friendly name for the TLS CA certificate.
tlscacertificate string TLS 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 Parameter Type Description
display_name string Customer friendly name for the TLS CA certificate.
identity string Unique identification for the TLS CA ertificate, Relative Resource Name
tlscacertificate string TLS CA Certificate as base64 string representing the contents of the PEM file
Responses Description
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 create a tlscacertificate.
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

Responses Description
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.
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 Parameter Type Description
display_name string Customer friendly name for the TLS CA certificate.
identity string Unique identification for the TLS CA ertificate, Relative Resource Name
tlscacertificate string TLS CA Certificate as base64 string representing the contents of the PEM file
Responses Description
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.
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-----"
}
Parameter Type Description
display_name string Customer friendly name for the TLS CA certificate.
identity string Unique identification for the TLS CA ertificate, Relative Resource Name
tlscacertificate string TLS CA Certificate as base64 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 Parameter Type Description
display_name string Customer friendly name for the TLS CA certificate.
identity string Unique identification for the TLS CA ertificate, Relative Resource Name
tlscacertificate string TLS CA Certificate as base64 string representing the contents of the PEM file
Responses Description
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.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

Edit this page on GitHub