LOG IN SIGN UP
Documentation

The Platform TLS Certificate Deployment Service is available to subscribers who have purchased the service.

Private Keys

A private key is used to sign a Certificate. A key can be used to sign multiple certificates.

Fields

field type description
created_at string

Time-stamp (GMT) when the private key was created. Read Only.

name string

A customizable name for your private key. Optional.

key string

The contents of the private key. Must be a PEM-formatted key. Not returned in response body. Required.

key_length integer

The key length used to generate the private key. Read Only.

key_type string

The algorithm used to generate the private key. Must be RSA. Read Only.

replace boolean

A recommendation from Fastly to replace this private key and all associated certificates. Read Only.

Actions

GET /tls/private_keys

List all private keys.

Authentication

API token with at least TLS management permissions.

Parameters
parameter type description
filter[in_use] string

Limit the returned keys to those without any matching TLS certificates. The only valid value is false.

page[number] integer

The page index for pagination.

page[size] integer

The number of keys per page.

Request Example
GET /tls/private_keys HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/vnd.api+json
Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": [
    {
      "id": "PRIVATE_KEY_ID",
      "type" : "tls_private_key",
      "attributes": {
        "created_at": "2018-06-06T18:14:32+00:00",
        "key_length": 2048,
        "key_type": "RSA",
        "name": "My private key",
        "replace": false
      }
    }
  ]
}
GET /tls/private_keys/id

List one private key.

Authentication

API token with at least TLS management permissions.

Request Example
GET /tls/private_keys/:id HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/vnd.api+json
Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "PRIVATE_KEY_ID",
    "type" : "tls_private_key",
    "attributes": {
      "created_at": "2018-06-06T18:14:32+00:00",
      "key_length": 2048,
      "key_type": "RSA",
      "name": "My private key",
      "replace": false
    }
  }
}
POST /tls/private_keys

Upload a private key.

Authentication

API token with at least TLS management permissions.

Request Example
POST /tls/private_keys HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data": {
    "type": "tls_private_key",
    "attributes": {
      "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "name": "My private key"
    }
  }
}
Response Example
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "PRIVATE_KEY_ID",
    "type": "tls_private_key",
    "attributes": {
      "created_at": "2018-06-06T18:14:32+00:00",
      "key_length": 2048,
      "key_type": "RSA",
      "name": "My private key",
      "replace": false
    }
  }
}
DELETE /tls/private_keys/id

Destroy a private key. Only private keys not already matched to any certificates can be deleted.

Authentication

API token with at least TLS management permissions.

Request Example
DELETE /tls/private_keys/PRIVATE_KEY_ID HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/vnd.api+json
Response Example
HTTP/1.1 204 No Content
Content-Type: application/vnd.api+json

Bulk Certificates

Available to Platform TLS customers, these endpoints streamline the upload, deployment and management of large numbers of TLS certificates. A certificate is used to terminate TLS traffic for one or more of your fully qualified domain names (domains). Uploading a new certificate automatically enables TLS for all domains listed as Subject Alternative Names (SAN entries) on the certificate.

Fields

field type description
cert_blob string

The PEM-formatted certificate blob. Required. Write Only.

created_at string

Time-stamp (GMT) when the certificate was created. Read Only.

intermediates_blob string

The PEM-formatted chain of intermediate blobs. Required. Write Only.

not_after string

Time-stamp (GMT) when the certificate will expire. Must be in the future to be used to terminate TLS traffic. Read Only.

not_before string

Time-stamp (GMT) when the certificate will become valid. Must be in the past to be used to terminate TLS traffic. Read Only.

replace boolean

A recommendation from Fastly indicating the key associated with this certificate is in need of rotation. Read Only.

updated_at string

Time-stamp (GMT) when the certificate was last updated. Read Only.

tls_configurations.id string

The identifier for the dedicated IP address pool that will be used to route traffic from the domain. Required.

tls_domains array

All the domains (including wildcard domains) that are listed in any certificate's Subject Alternative Names (SAN) list. Read Only.

Actions

GET /tls/bulk/certificates

List all certificates.

Authentication

API token with at least TLS management permissions.

Parameters
parameter type description
filter[tls_domain.id][match] string

Filter certificates by their matching, fully-qualified domain name. Returns all partial matches. Must provide a value longer than 3 characters.

page[number] integer

The page index for pagination.

page[size] integer

The number of certificates per page.

sort string

The order in which to list certificates. Valid values are created_at, not_before, not_after. May precede any value with a - for descending.

Request Example
GET /tls/bulk/certificates HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/vnd.api+json
Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": [
    {
      "id": "CERTIFICATE_ID",
      "type" : "tls_bulk_certificate",
      "attributes": {
        "not_after": "2019-06-06T18:14:32+00:00",
        "not_before": "2018-06-06T18:14:32+00:00",
        "created_at": "2018-06-06T18:14:32+00:00",
        "updated_at": "2018-06-06T18:14:32+00:00",
        "replace": false
      },
      "relationships": {
        "tls_configurations": {
          "data": [{
            "type": "tls_configuration",
            "id": "TLS_CONFIGURATION_ID"
          }]
        },
        "tls_domains": {
          "data": [{
            "type": "tls_domain",
            "id": "DOMAIN_NAME"
          }]
        }
      }
    }
  ]
}
GET /tls/bulk/certificates/id

Retrieve a single certificate.

Authentication

API token with at least TLS management permissions.

Request Example
GET /tls/bulk/certificates/:id HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/vnd.api+json
Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "CERTIFICATE_ID",
    "type" : "tls_bulk_certificate",
    "attributes": {
      "not_after": "2019-06-06T18:14:32+00:00",
      "not_before": "2018-06-06T18:14:32+00:00",
      "created_at": "2018-06-06T18:14:32+00:00",
      "updated_at": "2018-06-06T18:14:32+00:00",
      "replace": false
    },
    "relationships": {
      "tls_configurations": {
        "data": [{
          "type": "tls_configuration",
          "id": "TLS_CONFIGURATION_ID"
        }]
      },
      "tls_domains": {
        "data": [{
          "type": "tls_domain",
          "id": "DOMAIN_NAME"
        }]
      }
    }
  }
}
POST /tls/bulk/certificates

Upload a new certificate. TLS domains are automatically enabled upon certificate creation. If a domain is already enabled on a previously uploaded certificate, that domain will be updated to use the new certificate for all future TLS handshake requests.

Authentication

API token with at least TLS management permissions.

Request Example
POST /tls/bulk/certificates HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data" : {
    "type" : "tls_bulk_certificate",
    "attributes": {
      "cert_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "intermediates_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
    },
    "relationships": {
      "tls_configurations": {
        "data": [{
          "type": "tls_configuration",
          "id": "TLS_CONFIGURATION_ID"
        }]
      }
    }
  }
}
Response Example
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "CERTIFICATE_ID",
    "type": "tls_bulk_certificate",
    "attributes": {
      "not_after": "2019-06-06T18:14:32+00:00",
      "not_before": "2018-06-06T18:14:32+00:00",
      "created_at": "2018-06-06T18:14:32+00:00",
      "updated_at": "2018-06-06T18:14:32+00:00",
      "replace": false
    },
    "relationships": {
      "tls_configurations": {
        "data": [{
          "type": "tls_configuration",
          "id": "TLS_CONFIGURATION_ID"
        }]
      },
      "tls_domains": {
        "data": [{
          "type": "tls_domain",
          "id": "DOMAIN_NAME"
        }]
      }
    }
  }
}
PATCH /tls/bulk/certificates/id

Replace a certificate with a newly reissued certificate. By using this endpoint, the original certificate will cease to be used for future TLS handshakes. Thus, only SAN entries that appear in the replacement certificate will become TLS enabled. Any SAN entries that are missing in the replacement certificate will become disabled.

Authentication

API token with at least TLS management permissions.

Request Example
PATCH /tls/bulk/certificates/:id HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data" : {
    "id": "CERTIFICATE_ID",
    "type" : "tls_bulk_certificate",
    "attributes": {
      "cert_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "intermediates_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
    }
  }
}
Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "CERTIFICATE_ID",
    "type": "tls_bulk_certificate",
    "attributes": {
      "not_after": "2019-06-06T18:14:32+00:00",
      "not_before": "2018-06-06T18:14:32+00:00",
      "created_at": "2018-06-06T18:14:32+00:00",
      "updated_at": "2018-06-06T18:14:32+00:00",
      "replace": false
    },
    "relationships": {
      "tls_configurations": {
        "data": [{
          "type": "tls_configuration",
          "id": "TLS_CONFIGURATION_ID"
        }]
      },
      "tls_domains": {
        "data": [{
          "type": "tls_domain",
          "id": "DOMAIN_NAME"
        }]
      }
    }
  }
}
DELETE /tls/bulk/certificates/id

Destroy a certificate. This disables TLS for all domains listed as SAN entries.

Authentication

API token with at least TLS management permissions.

Request Example
DELETE /tls/bulk/certificates/CERTIFICATE_ID HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/vnd.api+json
Response Example
HTTP/1.1 204 No Content

Limitations and conditions

The Platform TLS Certificate Deployment Service has the following general limitations:

In addition, certificates are deployed using the Platform TLS Certificate Service with the following conditions: