Transport Layer Security (TLS) | Fastly API Documentation

IMPORTANT: This feature is part of a Beta release. Portions of this API may be subject to changes and improvements over time. Fields marked deprecated may be removed in the future and their use is discouraged. For more information, see our product and feature lifecycle descriptions.

Fastly offers an API for uploading and managing your keys and certificates used to enable TLS for your domains on Fastly.

To start, you must generate a new key and certificate with your preferred Certificate Authority. You may then use our endpoints to upload a key and then upload the matching certificate. To terminate TLS for a specific domain, you'll need to enable that domain for a given certificate by creating a protocol policy. Finally, for Fastly to begin to terminate TLS you will need to update the DNS records for the domain with the provided DNS Names returned to you.

We also provide a way for you to replace your certificates when they are nearing expiration. When regenerating a new certificate, you must ensure the list of SAN entries match the existing certificate. You can then replace the existing certificate with the new certificate.

This API also allows you to delete keys and certificates, list TLS domains for an uploaded certificate, and disable a protocol policy (which will disable TLS termination for that domain).

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.
public_key_sha1	string	Useful for safely identifying the key. Read Only.

Actions

GET /tls/private_keys

List all TLS 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

Response Example

{
  "data": [
    {
      "id": "PRIVATE_KEY_ID",
      "type": "tls_private_key",
      "attributes": {
        "key_length": 2048,
        "key_type": "RSA",
        "name": "My private key",
        "created_at": "2019-02-01T12:12:12.000Z",
        "replace": false,
        "public_key_sha1": "KEY_DIGEST"
      }
    }
  ]
}

GET /tls/private_keys/id

Show a TLS private key.

Authentication

API token with at least TLS management permissions.

Request Example

Response Example

{
  "data": {
    "id": "PRIVATE_KEY_ID",
    "type": "tls_private_key",
    "attributes": {
      "key_length": 2048,
      "key_type": "RSA",
      "name": "My private key",
      "created_at": "2019-02-01T12:12:12.000Z",
      "replace": false,
      "public_key_sha1": "KEY_DIGEST"
    }
  }
}

POST /tls/private_keys

Create a TLS private key.

Authentication

API token with at least TLS management permissions.

Request Example

{
  "data": {
    "type": "tls_private_key",
    "attributes": {
      "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "name": "My private key"
    }
  }
}

Response Example

{
  "data": {
    "id": "PRIVATE_KEY_ID",
    "type": "tls_private_key",
    "attributes": {
      "key_length": 2048,
      "key_type": "RSA",
      "name": "My private key",
      "created_at": null,
      "replace": false,
      "public_key_sha1": "KEY_DIGEST"
    }
  }
}

DELETE /tls/private_keys/id

Destroy a TLS 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

Response Example

TLS Certificates

A TLS certificate is used to terminate TLS traffic for one or more of your TLS domains.

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.
issued_to	string	The hostname for which a certificate was issued. Read Only.
issuer	string	The certificate authority that issued the certificate. Read Only.
name	string	A customizable name for your certificate. Defaults to the certificate's common name or first Subject Alternative Names (SAN) entry. Optional.
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.
serial_number	string	A value assigned by the issuer that is unique to a certificate. Read Only.
signature_algorithm	string	The algorithm used to sign the certificate. Read Only.
updated_at	string	Time-stamp (GMT) when the certificate was last updated. Read Only.
tls_domains	array	All the domains (including wildcard domains) that are listed in any certificate's Subject Alternative Names (SAN) list.

Actions

GET /tls/certificates

List all TLS certificates.

Authentication

API token with at least TLS management permissions.

Parameters

parameter	type	description
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

Response Example

{
  "data": [
    {
      "id": "TLS_CERTIFICATE_ID",
      "type": "tls_certificate",
      "attributes": {
        "created_at": "2019-02-01T12:12:12.000Z",
        "issued_to": "...",
        "issuer": "Let's Encrypt Authority X3",
        "name": "My certificate",
        "not_after": "2020-02-01T12:12:12.000Z",
        "not_before": "2019-02-01T12:12:12.000Z",
        "replace": false,
        "serial_number": "1234567890",
        "signature_algorithm": "SHA256",
        "updated_at": "2019-02-01T12:12:12.000Z"
      },
      "relationships": {
        "tls_domains": {
          "data": [
            { "id": "DOMAIN_NAME", "type": "tls_domain" }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://api.fastly.com/tls/certificates?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://api.fastly.com/tls/certificates?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://api.fastly.com/tls/certificates?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": { "per_page": 20, "current_page": 1, "record_count": 1, "total_pages": 1 }
}

GET /tls/certificates/id

Show a TLS certificate.

Authentication

API token with at least TLS management permissions.

Request Example

Response Example

{
  "data": {
    "id": "TLS_CERTIFICATE_ID",
    "type": "tls_certificate",
    "attributes": {
      "created_at": "2019-02-01T12:12:12.000Z",
      "issued_to": "...",
      "issuer": "Let's Encrypt Authority X3",
      "name": "My certificate",
      "not_after": "2020-02-01T12:12:12.000Z",
      "not_before": "2019-02-01T12:12:12.000Z",
      "replace": false,
      "serial_number": "1234567890",
      "signature_algorithm": "SHA256",
      "updated_at": "2019-02-01T12:12:12.000Z"
    },
    "relationships": {
      "tls_domains": {
        "data": [
          { "id": "DOMAIN_NAME", "type": "tls_domain" }
        ]
      }
    }
  }
}

POST /tls/certificates

Create a TLS certificate.

Authentication

API token with at least TLS management permissions.

Request Example

{
  "data": {
    "type": "tls_certificate",
    "attributes": {
      "cert_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "name": "My certificate"
    }
  }
}

Response Example

{
  "data": {
    "id": "TLS_CERTIFICATE_ID",
    "type": "tls_certificate",
    "attributes": {
      "created_at": "2019-02-01T12:12:12.000Z",
      "issued_to": "...",
      "issuer": "Let's Encrypt Authority X3",
      "name": "My certificate",
      "not_after": "2020-02-01T12:12:12.000Z",
      "not_before": "2019-02-01T12:12:12.000Z",
      "replace": false,
      "serial_number": "1234567890",
      "signature_algorithm": "SHA256",
      "updated_at": "2019-02-01T12:12:12.000Z"
    },
    "relationships": {
      "tls_domains": {
        "data": [
          { "id": "DOMAIN_NAME", "type": "tls_domain" }
        ]
      }
    }
  }
}

PATCH /tls/certificates/id

Replace a TLS certificate with a newly reissued TLS certificate, or update a TLS certificate's name. If replacing a TLS certificate, the new TLS certificate must contain all SAN entries as the current TLS certificate. It must either have an exact matching list or contain a superset.

Authentication

API token with at least TLS management permissions.

Request Example

{
  "data": {
    "type": "tls_certificate",
    "attributes": {
      "cert_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "name": "My certificate"
    }
  }
}

Response Example

{
  "data": {
    "id": "TLS_CERTIFICATE_ID",
    "type": "tls_certificate",
    "attributes": {
      "created_at": "2019-02-01T12:12:12.000Z",
      "issued_to": "...",
      "issuer": "Let's Encrypt Authority X3",
      "name": "My certificate",
      "not_after": "2020-02-01T12:12:12.000Z",
      "not_before": "2019-02-01T12:12:12.000Z",
      "replace": false,
      "serial_number": "1234567890",
      "signature_algorithm": "SHA256",
      "updated_at": "2019-02-01T12:12:12.000Z"
    },
    "relationships": {
      "tls_domains": {
        "data": [
          { "id": "DOMAIN_NAME", "type": "tls_domain" }
        ]
      }
    }
  }
}

DELETE /tls/certificates/id

Destroy a TLS certificate. TLS certificates already enabled for a domain cannot be destroyed.

Authentication

API token with at least TLS management permissions.

Request Example

Response Example

TLS Domains

TLS domains are all the domains (including wildcard domains) included in any TLS certificate's Subject Alternative Names (SAN) list. Included in the response is information about which certificates reference this domain as well as the TLS activation indicating which certificate is enabled to serve TLS traffic for the domain.

Fields

field	type	description
id	string	The domain name. Read Only.
tls_certificates	array	The list of all the TLS certificates that include this domain in their SAN list.
tls_activations	array	The list of TLS activations that exist for the domain. If empty, then this domain is not enabled to serve TLS traffic.

Actions

GET /tls/domains

List all TLS domains.

Authentication

API token with at least TLS management permissions.

Parameters

parameter	type	description
filter[tls_certificates.id]	string	Optional. Limit the returned domains to those listed in the given TLS certificate's SAN list.
include	string	Include related objects. Optional, comma-separated values. Permitted values: `tls_activations`, `tls_certificates`, `tls_subscriptions`, and `tls_subscriptions.tls_authorizations`.
page[number]	integer	The page index for pagination.
page[size]	integer	The number of domains per page.

Request Example

Response Example

{
  "data": [
    {
      "id": "DOMAIN_NAME",
      "type": "tls_domain",
      "relationships": {
        "tls_activations": {
          "data": [
            { "id": "TLS_ACTIVATION_ID", "type": "tls_activation" }
          ]
        },
        "tls_certificates": {
          "data": [
            { "id": "TLS_CERTIFICATE_ID", "type": "tls_certificate" }
          ]
        },
        "tls_subscriptions": {
          "data": [
            { "id": "TLS_SUBSCRIPTION_ID", "type": "tls_subscription" }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://api.fastly.com/tls/domains?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://api.fastly.com/tls/domains?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://api.fastly.com/tls/domains?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": { "record_count": 1, "current_page": 1, "per_page": 20, "total_pages": 1 }
}

TLS Activations

Fields

field	type	description
tls_certificate.id	string	The TLS certificate being used to terminate TLS traffic for a domain. Required.
tls_configuration.id	string	The TLS configuration being used to terminate TLS traffic. Optional.
tls_domain.id	string	The TLS domain being enabled for TLS traffic. Required.

Actions

GET /tls/activations

List all TLS activations.

Authentication

API token with at least TLS management permissions.

Parameters

parameter	type	description
filter[tls_certificate.id]	string	Limit the returned activations to a specific certificate.
filter[tls_configuration.id]	string	Limit the returned activations to a specific TLS configuration.
filter[tls_domain.id]	string	Limit the returned rules to a specific domain name.
include	string	Include related objects. Optional, comma-separated values. Permitted values: `tls_certificate`, `tls_configuration`, and `tls_domain`.
page[number]	integer	The page index for pagination.
page[size]	integer	The number of activations per page.

Request Example

Response Example

{
  "data": [
    {
      "id": "TLS_ACTIVATION_ID",
      "type": "tls_activation",
      "attributes": { "created_at": "2019-02-01T12:12:12.000Z" },
      "relationships": {
        "tls_certificate": {
          "data": { "id": "TLS_CERTIFICATE_ID", "type": "tls_certificate" }
        },
        "tls_configuration": {
          "data": { "id": "TLS_CONFIGURATION_ID", "type": "tls_configuration" }
        },
        "tls_domain": {
          "data": { "id": "DOMAIN_NAME", "type": "tls_domain" }
        }
      }
    }
  ],
  "links": {
    "self": "https://api.fastly.com/tls/activations?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "first": "https://api.fastly.com/tls/activations?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "prev": null,
    "next": null,
    "last": "https://api.fastly.com/tls/activations?page%5Bnumber%5D=1&page%5Bsize%5D=100"
  },
  "meta": { "per_page": 100, "current_page": 1, "record_count": 1, "total_pages": 1 }
}

GET /tls/activations/id

Show a TLS activation.

Authentication

API token with at least TLS management permissions.

Parameters

parameter	type	description
include	string	Include related objects. Optional, comma-separated values. Permitted values: `tls_certificate`, `tls_configuration`, and `tls_domain`.

Request Example

Response Example

{
  "data": {
    "id": "TLS_ACTIVATION_ID",
    "type": "tls_activation",
    "attributes": { "created_at": "2019-02-01T12:12:12.000Z" },
    "relationships": {
      "tls_certificate": {
        "data": { "id": "TLS_CERTIFICATE_ID", "type": "tls_certificate" }
      },
      "tls_configuration": {
        "data": { "id": "TLS_CONFIGURATION_ID", "type": "tls_configuration" }
      },
      "tls_domain": {
        "data": { "id": "DOMAIN_NAME", "type": "tls_domain" }
      }
    }
  }
}

POST /tls/activations

Enable TLS for a particular TLS domain and certificate combination. These relationships must be specified to create the TLS activation.

Authentication

API token with at least TLS management permissions.

Request Example

{
  "data": {
    "type": "tls_activation",
    "relationships": {
      "tls_certificate": {
        "data": { "type": "tls_certificate", "id": "TLS_CERTIFICATE_ID" }
      },
      "tls_configuration": {
        "data": { "type": "tls_configuration", "id": "TLS_CONFIGURATION_ID" }
      },
      "tls_domain": {
        "data": { "type": "tls_domain", "id": "DOMAIN_NAME" }
      }
    }
  }
}

Response Example

{
  "data": {
    "id": "TLS_ACTIVATION_ID",
    "type": "tls_activation",
    "attributes": { "created_at": "2019-02-01T12:12:12.000Z" },
    "relationships": {
      "tls_certificate": {
        "data": { "id": "TLS_CERTIFICATE_ID", "type": "tls_certificate" }
      },
      "tls_configuration": {
        "data": { "id": "TLS_CONFIGURATION_ID", "type": "tls_configuration" }
      },
      "tls_domain": {
        "data": { "id": "DOMAIN_NAME", "type": "tls_domain" }
      }
    }
  }
}

PATCH /tls/activations/id

Update the certificate used to terminate TLS traffic for the domain associated with this TLS activation.

Authentication

API token with at least TLS management permissions.

Request Example

{
  "data": {
    "type": "tls_activation",
    "relationships": {
      "tls_certificate": {
        "data": { "type": "tls_certificate", "id": "CERTIFICATE_ID" }
      }
    }
  }
}

Response Example

{
  "data": {
    "id": "TLS_ACTIVATION_ID",
    "type": "tls_activation",
    "attributes": { "created_at": "2019-02-01T12:12:12.000Z" },
    "relationships": {
      "tls_certificate": {
        "data": { "id": "CERTIFICATE_ID", "type": "tls_certificate" }
      },
      "tls_configuration": {
        "data": { "id": "TLS_CONFIGURATION_ID", "type": "tls_configuration" }
      },
      "tls_domain": {
        "data": { "id": "DOMAIN_NAME", "type": "tls_domain" }
      }
    }
  }
}

DELETE /tls/activations/id

Disable TLS on the domain associated with this TLS activation.

Authentication

API token with at least TLS management permissions.

Request Example

Response Example

DNS Records

DNS records are the available DNS addresses that can be used to enable TLS for a domain. DNS must be configured for a domain for TLS handshakes to succeed. If enabling TLS on an apex domain (e.g., example.com) you must create four A records (or four AAAA records for IPv6 support) using the displayed global A record's IP addresses with your DNS provider. For subdomains and wildcard domains (e.g., www.example.com or *.example.com) you will need to create a relevant CNAME record.

Fields

field	type	description
id	string	The IP address or hostname of the DNS record.
region	string	Specifies the regions that will be used to route traffic. Select DNS Records with a `global` region to route traffic to the most performant point of presence (POP) worldwide (global pricing will apply). Select DNS records with a `us-eu` region to exclusively land traffic on North American and European POPs.
record_type	string	The type of the DNS record. `A` specifies an IPv4 address to be used for an A record to be used for apex domains (e.g., `example.com`). `AAAA` specifies an IPv6 address for use in an A record for apex domains. `CNAME` specifies the hostname to be used for a CNAME record for subdomains or wildcard domains (e.g., `www.example.com` or `*.example.com`).