LOG IN SIGN UP
Documentation
  2. API
  3. Transport Layer Security (TLS)

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.

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

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
GET /tls/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_certificate",
      "attributes": {
        "created_at": "2018-06-06T18:14:32+00:00",
        "issued_to": "my-domain.com",
        "issuer": "Let's Encrypt Authority X3",
        "name": "My certificate"
        "not_after": "2019-06-06T18:14:32+00:00",
        "not_before": "2018-06-06T18:14:32+00:00",
        "replace": false,
        "serial_number": "1234567890",
        "signature_algorithm": "SHA256-RSA",
        "updated_at": "2018-06-06T18:14:32+00:00"
      },
      "relationships": {
        "tls_domains": {
          "data": [{
            "type": "tls_domain",
            "id": "DOMAIN_NAME"
          }]
        }
      }
    }
  ]
}
GET /tls/certificates/id

List one TLS certificate.

Authentication

API token with at least TLS management permissions.

Request Example
GET /tls/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_certificate",
    "attributes": {
      "created_at": "2018-06-06T18:14:32+00:00",
      "issued_to": "my-domain.com",
      "issuer": "Let's Encrypt Authority X3",
      "name": "My certificate"
      "not_after": "2019-06-06T18:14:32+00:00",
      "not_before": "2018-06-06T18:14:32+00:00",
      "replace": false,
      "serial_number": "1234567890",
      "signature_algorithm": "SHA256-RSA",
      "updated_at": "2018-06-06T18:14:32+00:00"
    },
    "relationships": {
      "tls_domains": {
        "data": [{
          "type": "tls_domain",
          "id": "DOMAIN_NAME"
        }]
      }
    }
  }
}
POST /tls/certificates

Upload a new TLS certificate.

Authentication

API token with at least TLS management permissions.

Request Example
POST /tls/certificates HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data" : {
    "type" : "tls_certificate",
    "attributes": {
      "cert_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "name": "My certificate"
    }
  }
}
Response Example
 
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "CERTIFICATE_ID",
    "type": "tls_certificate",
    "attributes": {
      "created_at": "2018-06-06T18:14:32+00:00",
      "issued_to": "my-domain.com",
      "issuer": "Let's Encrypt Authority X3",
      "name": "My certificate",
      "not_after": "2019-06-06T18:14:32+00:00",
      "not_before": "2018-06-06T18:14:32+00:00",
      "replace": false,
      "serial_number": "1234567890",
      "signature_algorithm": "SHA256-RSA",
      "updated_at": "2018-06-06T18:14:32+00:00"
    },
    "relationships": {
      "tls_domains": {
        "data": [{
          "type": "tls_domain",
          "id": "DOMAIN_NAME"
        }]
      }
    }
  }
}
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 have the exact same list of SAN entries as the current TLS certificate.

Authentication

API token with at least TLS management permissions.

Request Example
PATCH /tls/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_certificate",
    "attributes": {
      "cert_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "name": "My certificate"
    }
  }
}
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "CERTIFICATE_ID",
    "type": "tls_certificate",
    "attributes": {
      "created_at": "2018-06-06T18:14:32+00:00",
      "issued_to": "my-domain.com",
      "issuer": "Let's Encrypt Authority X3",
      "name": "My certificate",
      "not_after": "2019-06-06T18:14:32+00:00",
      "not_before": "2018-06-06T18:14:32+00:00",
      "replace": false,
      "serial_number": "1234567890",
      "signature_algorithm": "SHA256-RSA",
      "updated_at": "2018-06-06T18:14:32+00:00"
    },
    "relationships": {
      "tls_domains": {
        "data": [{
          "type": "tls_domain",
          "id": "DOMAIN_NAME"
        }]
      }
    }
  }
}
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
DELETE /tls/certificates/CERTIFICATE_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

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.
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.
tls_activations.dns_records array

The list of DNS records available to configure DNS for the domain for a specific TLS activation.

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

Limit the returned domains to those listed in the given TLS certificate's SAN list. Optional.
include string

Include related objects. Optional, comma-separated values. Permitted values: tls_activations, tls_activations.dns_records.
page[number] integer

The page index for pagination.
page[size] integer

The number of domains per page.
Request Example
GET /tls/domains?include=tls_activations,tls_activations.dns_records 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": "DOMAIN_NAME",
    "type": "tls_domain",
    "relationships": {
      "tls_certificates": {
        "data": [
          {
            "id": "CERTIFICATE_ID",
            "type": "tls_certificate",
          },
        ],
      },
      "tls_activations": {
        "data": [
          {
            "id": "TLS_ACTIVATION_ID",
            "type": "tls_activation"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "TLS_ACTIVATION_ID",
      "type": "tls_activation",
      "relationships": {
        "tls_certificate": {
          "data": {
            "id": "CERTIFICATE_ID",
            "type": "tls_certificate",
          },
        },
        "dns_records": {
          "data": [
            { "id": "151.101.2.133", "type": "dns_record" },
            { "id": "151.101.66.133", "type": "dns_record" },
            { "id": "151.101.130.133", "type": "dns_record" },
            { "id": "151.101.194.133", "type": "dns_record" },
            { "id": "2a04:4e42::645", "type": "dns_record" },
            { "id": "2a04:4e42:200::645", "type": "dns_record" },
            { "id": "2a04:4e42:400::645", "type": "dns_record" },
            { "id": "2a04:4e42:600::645", "type": "dns_record" },
            { "id": "d.sni.global.fastly.net", "type": "dns_record" },
            { "id": "d.sni.us-eu.fastly.net", "type": "dns_record" },
          ],
        },
      },
    },
    { "id": "151.101.2.133", "type": "dns_record", "attributes": { "region": "global", "record_type": "A" } },
    { "id": "151.101.66.133", "type": "dns_record", "attributes": { "region": "global", "record_type": "A" } },
    { "id": "151.101.130.133", "type": "dns_record", "attributes": { "region": "global", "record_type": "A" } },
    { "id": "151.101.194.133", "type": "dns_record", "attributes": { "region": "global", "record_type": "A" } },
    { "id": "2a04:4e42::645", "type": "dns_record", "attributes": { "region": "global", "record_type": "AAAA" } },
    { "id": "2a04:4e42:200::645", "type": "dns_record", "attributes": { "region": "global", "record_type": "AAAA" } },
    { "id": "2a04:4e42:400::645", "type": "dns_record", "attributes": { "region": "global", "record_type": "AAAA" } },
    { "id": "2a04:4e42:600::645", "type": "dns_record", "attributes": { "region": "global", "record_type": "AAAA" } },
    { "id": "d.sni.global.fastly.net", "type": "dns_record", "attributes": { "region": "global", "record_type": "CNAME" } },
    { "id": "d.sni.us-eu.fastly.net", "type": "dns_record", "attributes": { "region": "us-eu", "record_type": "CNAME" } },
  ],
}

TLS Activations

Fields

field type description
certificate.id string

The TLS certificate being used to terminate TLS traffic for a domain. Required.
tls_domain.id string

The TLS domain being enabled for TLS traffic. Required.
dns_records array

A list of available DNS records for configuring the TLS domain. Read Only.

Actions

POST /tls/activations

Enable TLS for a particular TLS domain and certificate combination. These two relationships must be specified to create the TLS activation. The returned DNS records should be used to configure DNS for the domain to successfully serve TLS traffic.

Authentication

API token with at least TLS management permissions.

Request Example
POST /tls/activations HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data": {
    "type": "tls_activation",
    "relationships": {
      "tls_certificate": {
        "data": {
          "type": "tls_certificate",
          "id": "CERTIFICATE_ID",
        }
      },
      "tls_domain": {
        "data": {
          "type": "tls_domain",
          "id": "DOMAIN_NAME",
        }
      }
    }
  }
}
Response Example
 
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "TLS_ACTIVATION_ID",
    "type": "tls_activation",
    "relationships": {
      "tls_certificate": {
        "data": {
          "id": "CERTIFICATE_ID",
          "type": "tls_certificate"
        }
      },
      "tls_domain": {
        "data": {
          "type": "tls_domain",
          "id": "DOMAIN_NAME",
        }
      },
      "dns_records": {
        "data": [
          { "id": "151.101.2.133", "type": "dns_record" },
          { "id": "151.101.66.133", "type": "dns_record" },
          { "id": "151.101.130.133", "type": "dns_record" },
          { "id": "151.101.194.133", "type": "dns_record" },
          { "id": "2a04:4e42::645", "type": "dns_record" },
          { "id": "2a04:4e42:200::645", "type": "dns_record" },
          { "id": "2a04:4e42:400::645", "type": "dns_record" },
          { "id": "2a04:4e42:600::645", "type": "dns_record" },
          { "id": "d.sni.global.fastly.net", "type": "dns_record" },
          { "id": "d.sni.us-eu.fastly.net", "type": "dns_record" }
        ],
      },
    },
    "included": [
      { "id": "151.101.2.133", "type": "dns_record", "attributes": { "region": "global", "record_type": "A" } },
      { "id": "151.101.66.133", "type": "dns_record", "attributes": { "region": "global", "record_type": "A" } },
      { "id": "151.101.130.133", "type": "dns_record", "attributes": { "region": "global", "record_type": "A" } },
      { "id": "151.101.194.133", "type": "dns_record", "attributes": { "region": "global", "record_type": "A" } },
      { "id": "2a04:4e42::645", "type": "dns_record", "attributes": { "region": "global", "record_type": "AAAA" } },
      { "id": "2a04:4e42:200::645", "type": "dns_record", "attributes": { "region": "global", "record_type": "AAAA" } },
      { "id": "2a04:4e42:400::645", "type": "dns_record", "attributes": { "region": "global", "record_type": "AAAA" } },
      { "id": "2a04:4e42:600::645", "type": "dns_record", "attributes": { "region": "global", "record_type": "AAAA" } },
      { "id": "d.sni.global.fastly.net", "type": "dns_record", "attributes": { "region": "global", "record_type": "CNAME" } },
      { "id": "d.sni.us-eu.fastly.net", "type": "dns_record", "attributes": { "region": "us-eu", "record_type": "CNAME" } }
    ],
  },
}
PATCH /tls/activations/id

Update the certificate used to terminate TLS traffic for the domain associated with this TLS activation. DNS record relationships are returned, though no adjustments to DNS records are required when switching a domain from one certificate to another.

Authentication

API token with at least TLS management permissions.

Request Example
PATCH /tls/activations/TLS_ACTIVATION_ID HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data": {
    "id": "TLS_ACTIVATION_ID",
    "type": "tls_activation",
    "relationships": {
      "tls_certificate": {
        "data": {
          "type": "tls_certificate",
          "id": "CERTIFICATE_ID",
        }
      }
    }
  }
}
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "TLS_ACTIVATION_ID",
    "type": "tls_activation",
    "relationships": {
      "tls_certificate": {
        "data": {
          "id": "CERTIFICATE_ID",
          "type": "tls_certificate"
        }
      },
      "tls_domain": {
        "data": {
          "type": "tls_domain",
          "id": "DOMAIN_NAME",
        }
      },
      "dns_records": {
        "data": [
          { "id": "151.101.2.133", "type": "dns_record" },
          { "id": "151.101.66.133", "type": "dns_record" },
          { "id": "151.101.130.133", "type": "dns_record" },
          { "id": "151.101.194.133", "type": "dns_record" },
          { "id": "2a04:4e42::645", "type": "dns_record" },
          { "id": "2a04:4e42:200::645", "type": "dns_record" },
          { "id": "2a04:4e42:400::645", "type": "dns_record" },
          { "id": "2a04:4e42:600::645", "type": "dns_record" },
          { "id": "d.sni.global.fastly.net", "type": "dns_record" },
          { "id": "d.sni.us-eu.fastly.net", "type": "dns_record" }
        ],
      },
    },
  },
}
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
DELETE /tls/activations/TLS_ACTIVATION_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

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).