Last updated 2021-07-15
Fastly's Platform TLS product allows you to programmatically manage certificates and keys for Transport Layer Security (TLS) using a web API.
Consider this product if:
- you need to support thousands of individual X.509 certificates and their associated private keys.
- you own and generate your own certificates and private keys (typically obtained from a third-party certification authority such as Let’s Encrypt).
For more information about this product, contact email@example.com.
This information is part of a limited availability release. For more information, see our product and feature lifecycle descriptions.
How Platform TLS works
Platform TLS allows you to programmatically manage certificates and private keys on a special Fastly service provisioned for use with the Platform TLS API. Using the API, you can:
- deploy new X.509 certificates
- retrieve information about deployed certificates
- update and delete existing certificates
- deploy new private keys
- retrieve information about private keys
- delete private keys
You can support your entire certificate lifecycle by replacing expiring certificates with newly generated ones at any time and using the API to rotate your private keys to manage your key management requirements.
Initial setup and configuration
The Platform TLS product will be provisioned by Fastly staff on a dedicated IP address pool (which you purchase separately) in Fastly's infrastructure. We configure your service to skip domain lookups and instead route client requests directly to your service based on the destination IP address that a client is connecting to. Because multiple certificates are served off the same IP address pool, Server Name Indication (SNI) is required for this product to work properly. We then provide you with a custom DNS map to use in your CNAME records and the corresponding Anycast IP addresses (for use with any apex domains you serve through Fastly).
Once setup is complete, certificates you upload using the API will automatically be made available to your dedicated IP address pool. Browser clients initiating a TLS handshake will automatically receive the proper certificate based on the domain indicated in the TLS handshake.
Certificate and key uploads and renewals
Once setup and configuration are complete, you can upload TLS private keys and matching TLS certificates using the Platform TLS API. The Platform TLS product automatically matches certificates to previously uploaded keys. TLS certificates may be procured from the certification authority (CA) of your choice.
When renewing and replacing certificates nearing expiration, you must procure new ones from your CA and then use the Platform TLS API to upload their replacements. You may also rotate your private keys. Any time you decide to swap out your key with a new one, that new key would need to be uploaded first, and then all the certificates associated with the old key would need to be regenerated and uploaded.
To begin serving traffic through Fastly with the Platform TLS product, you or your customers must modify DNS records for any web properties to point traffic to the IP address pool assigned for your service. Fastly will assign a DNS name for use with your DNS records that can support a CNAME record and the Anycast IPs that can be used with apex domains.
Using a CNAME record. With this option, a CNAME record gets created with a DNS provider and points to a custom DNS map Fastly provides. This option should be used for subdomains or wildcard domains (e.g.,
Using an A record. With this option, an A record gets created with a DNS provider and points to an Anycast address that Fastly provides. This option should be used for apex domains (e.g.,
example.com). Map names and Anycast addresses will be provided during initial setup and configuration. To obtain this information again, contact firstname.lastname@example.org.
For each of your domains, a CNAME or an A record must have been created with a DNS provider and you must have activated a Fastly service for traffic to be properly directed through it.
How TLS is enforced when you have multiple certificates
Fastly will automatically choose the certificate to be delivered for a given request based on the Host requested. The certificate with the most specific matching hostname will be preferred over certificates with less specific hostnames. Fastly's TLS server will always prefer an exact match SAN entry to a wildcard match. For example, on a request for
api.example.com, Fastly will serve a certificate with a SAN entry for
api.example.com over a different certificate with a SAN entry for
Conditions and limitations
When using Platform TLS, you agree to the following conditions:
- You are responsible for procuring your own certificates from the CA of your choice. Fastly will not procure certificates on your behalf.
- You are responsible for updating certificates prior to expiration. Expired certificates will cause TLS handshake failures that most browsers will display as site errors.
When using Platform TLS, you agree to the following limitations:
- This product requires a dedicated IP address pool on Fastly’s infrastructure. If you've previously purchased a dedicated IP address pool from Fastly, Platform TLS may be enabled on it.
- The certificate deployment process is not instantaneous. It takes approximately 20 minutes on average to complete once a certificate is submitted, though the deployment may take as long as one hour.
- If two certificates are uploaded with identical hostnames, the most recently uploaded certificate will be chosen.
- By default certificates uploaded via the Platform API should not exceed one domain per certificate.
As with all API-based activities, standard API rate limits apply.