TLS CA Certificates API

TLS CA Certificates API Reference

This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance. If you are looking for a simple way to test our API you might prefer our Postman collection, the YAML runner or the Developers section of the web UI.
Additional YAML examples can be found in the articles in the Overview section.

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 DataTrails 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 "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/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 DataTrails 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 "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/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 "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/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 "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/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 "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    https://app.datatrails.ai/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 "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/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
200	A successful response.
400	Returned when the request is badly formed.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to read the TLS CA certificate.
429	Returned when a user exceeds their subscription’s rate limit for requests.
500	Returned when the underlying storage system returns an error.

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
200	A successful response.
400	Returned when the request is badly formed.
401	Returned when the user is not authenticated to the system.
402	Returned when the user’s quota of certificates has been reached.
403	Returned when the user is not authorized to create a tlscacertificate.
429	Returned when a user exceeds their subscription’s rate limit for requests.
500	Returned when the underlying storage system returns an error.

delete /archivist/v1/tlscacertificates/{uuid}

Delete a TLS C Acertificate

Description: Delete the identified tLS CA Certificate

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

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
200	A successful response.
400	Returned when the request is badly formed.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to read the TLS CA certificate.
404	Returned when the identified TLS CA certificate does not exist.
429	Returned when a user exceeds their subscription’s rate limit for requests.
500	Returned when the underlying storage system returns an error.

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 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
200	A successful response.
400	Returned when the request is badly formed.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to update the TLS CA certificate.
404	Returned when the identified TLS C Acertificate does not exist.
429	Returned when a user exceeds their subscription’s rate limit for requests.
500	Returned when the underlying storage system returns an error.

get /archivist/v1/tlscacertificates:openapi

Get OpenAPI spec for TLSCACertificates

Description: Get OpenAPI v2.0 spec for TLSCACertificates

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

TLS CA Certificates API

TLS CA Certificates API Examples#

TLS CA Certificate Upload#

TLS CA Certificate Retrieval#

Fetch All TLS CA Certificates#

Fetch Specific TLS CA Certificate by Identity#

Fetch TLS CA Certificates by Name#

TLS CA Certificate Deletion#

Updating a TLS CA Certificate#

TLS CA Certificates OpenAPI Docs#

get /archivist/v1/tlscacertificates

get /archivist/v1/tlscacertificates

List TLS CA certificates

Example Response

post /archivist/v1/tlscacertificates

post /archivist/v1/tlscacertificates

Upload a TLS CA certificate

Example Request

Example Response

delete /archivist/v1/tlscacertificates/{uuid}

delete /archivist/v1/tlscacertificates/{uuid}

Delete a TLS C Acertificate

get /archivist/v1/tlscacertificates/{uuid}

get /archivist/v1/tlscacertificates/{uuid}

Get a TLS CA certificate

Example Response

patch /archivist/v1/tlscacertificates/{uuid}

patch /archivist/v1/tlscacertificates/{uuid}

Update a TLS CA certificate's details

Example Response

get /archivist/v1/tlscacertificates:openapi

get /archivist/v1/tlscacertificates:openapi

Get OpenAPI spec for TLSCACertificates

TLS CA Certificates API Examples

TLS CA Certificate Upload

TLS CA Certificate Retrieval

Fetch All TLS CA Certificates

Fetch Specific TLS CA Certificate by Identity

Fetch TLS CA Certificates by Name

TLS CA Certificate Deletion

Updating a TLS CA Certificate

TLS CA Certificates OpenAPI Docs