← Files Fastly Agent ToolkitARCHIVED FILE
skills/fastly/references/tls.md
15.2 KB · Oct 10, 2026 · 18:29 UTC
# Fastly TLS Configuration
Base: `https://api.fastly.com` | Auth: `Fastly-Key: $FASTLY_API_TOKEN` | Content-Type: `application/vnd.api+json` | Docs: https://www.fastly.com/documentation/reference/api/tls
Three approaches: **Platform TLS** (managed certs via Certainly/Let's Encrypt/GlobalSign), **Custom TLS** (upload your own certs), **Bulk/Platform TLS Certificates** (upload certs at scale with auto-activation).
## Platform TLS Subscriptions
| Action | Method | Endpoint |
| ------------------- | -------- | ------------------------------------------ |
| List subscriptions | `GET` | `/tls/subscriptions` |
| Create subscription | `POST` | `/tls/subscriptions` |
| Get subscription | `GET` | `/tls/subscriptions/{tls_subscription_id}` |
| Update subscription | `PATCH` | `/tls/subscriptions/{tls_subscription_id}` |
| Delete subscription | `DELETE` | `/tls/subscriptions/{tls_subscription_id}` |
Subscription states: `pending` -> `processing` -> `issued`. Renewals: `issued` -> `renewing` -> `issued`. Failures: any state -> `failed`.
| State | Meaning | Action |
| ------------ | ------------------------------ | ---------------------------------------------- |
| `pending` | Awaiting DNS challenge records | Configure DNS, then wait |
| `processing` | DNS validated, CA issuing cert | Wait (typically 1-5 minutes) |
| `issued` | Certificate live and active | Done |
| `renewing` | Auto-renewal in progress | No action needed |
| `failed` | Issuance failed | Check warnings, fix, PATCH with `state: retry` |
Authorization states (in `tls_authorizations`): `blocked` (DNS not configured or CAA conflict) -> challenge validated -> cert issued. Check `included[].attributes.warnings` for details on `blocked` state.
Certificate authorities: `certainly`, `lets-encrypt`, `globalsign`. Migrate between CAs via PATCH `certificate_authority`; to migrate from 'globalsign' to 'certainly', contact Fastly Support. To retry a `failed` subscription, PATCH with `state: retry`.
**CAA record verification.** Before choosing a CA, check the domain's CAA records with `dig CAA example.com +short`. If a CAA record restricts issuance (e.g., `0 issue "letsencrypt.org"`), the subscription's CA must match. Using a different CA (e.g., `certainly`) will result in a `blocked` authorization with warning `"Found conflicting CAA record(s)"`. If no CAA records exist, any CA works.
| CA | Required CAA `issue` value |
| -------------- | -------------------------- |
| `lets-encrypt` | `letsencrypt.org` |
| `certainly` | `certainly.com` |
| `globalsign` | `globalsign.com` |
List filters: `filter[state]`, `filter[tls_domains.id]`, `filter[has_active_order]`, `filter[certificate_authority]`. Include: `tls_authorizations` (required to get DNS challenge records), `tls_certificates`.
Delete requires no domains in TLS-enabled state. Use `force=true` query param on PATCH or DELETE with active domains (may break TLS).
```bash
# Create a Platform TLS subscription
curl -X POST -H "Fastly-Key: $FASTLY_API_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
-d '{"data":{"type":"tls_subscription","attributes":{"certificate_authority":"certainly"},"relationships":{"tls_domains":{"data":[{"type":"tls_domain","id":"www.example.com"}]},"tls_configuration":{"data":{"type":"tls_configuration","id":"CONFIG_ID"}}}}}' \
"https://api.fastly.com/tls/subscriptions"
# Check subscription status (include authorization challenges)
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/tls/subscriptions/{tls_subscription_id}?include=tls_authorizations"
# Retry a failed subscription
curl -X PATCH -H "Fastly-Key: $FASTLY_API_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
-d '{"data":{"type":"tls_subscription","attributes":{"state":"retry"}}}' \
"https://api.fastly.com/tls/subscriptions/{tls_subscription_id}"
```
## Custom TLS Certificates
| Action | Method | Endpoint |
| ------------------ | -------- | --------------------------------------------- |
| List certificates | `GET` | `/tls/certificates` |
| Create certificate | `POST` | `/tls/certificates` |
| Get certificate | `GET` | `/tls/certificates/{tls_certificate_id}` |
| Update certificate | `PATCH` | `/tls/certificates/{tls_certificate_id}` |
| Delete certificate | `DELETE` | `/tls/certificates/{tls_certificate_id}` |
| Get cert blob (LA) | `GET` | `/tls/certificates/{tls_certificate_id}/blob` |
Upload requires PEM-formatted `cert_blob`. Update (replace) requires the new cert to contain all existing SAN entries (superset OK). Cannot delete a cert that is active for a domain.
## TLS Private Keys
| Action | Method | Endpoint |
| ---------- | -------- | ---------------------------------------- |
| List keys | `GET` | `/tls/private_keys` |
| Create key | `POST` | `/tls/private_keys` |
| Get key | `GET` | `/tls/private_keys/{tls_private_key_id}` |
| Delete key | `DELETE` | `/tls/private_keys/{tls_private_key_id}` |
PEM-formatted via `key` attribute (write-only, never returned). Response includes `key_type`, `key_length`, `public_key_sha1`. Filter unused keys: `filter[in_use]=false`. Cannot delete a key matched to any certificate.
## TLS Activations
| Action | Method | Endpoint |
| --------------------- | -------- | -------------------------------------- |
| List activations | `GET` | `/tls/activations` |
| Enable TLS for domain | `POST` | `/tls/activations` |
| Get activation | `GET` | `/tls/activations/{tls_activation_id}` |
| Update certificate | `PATCH` | `/tls/activations/{tls_activation_id}` |
| Disable TLS | `DELETE` | `/tls/activations/{tls_activation_id}` |
Create links three resources via `relationships`: a `tls_certificate`, a `tls_configuration`, and a `tls_domain`. Filters: `filter[tls_certificate.id]`, `filter[tls_configuration.id]`, `filter[tls_domain.id]`. Include: `tls_certificate`, `tls_configuration`, `tls_domain`.
```bash
# Upload a custom cert (key must already exist)
curl -X POST -H "Fastly-Key: $FASTLY_API_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
-d '{"data":{"type":"tls_certificate","attributes":{"cert_blob":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----","name":"My cert"}}}' \
"https://api.fastly.com/tls/certificates"
# Activate TLS on a domain with a custom cert
curl -X POST -H "Fastly-Key: $FASTLY_API_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
-d '{"data":{"type":"tls_activation","relationships":{"tls_certificate":{"data":{"id":"CERT_ID","type":"tls_certificate"}},"tls_configuration":{"data":{"id":"CONFIG_ID","type":"tls_configuration"}},"tls_domain":{"data":{"id":"www.example.com","type":"tls_domain"}}}}}' \
"https://api.fastly.com/tls/activations"
```
## TLS Configurations
| Action | Method | Endpoint |
| -------------------- | ------- | -------------------------------------------- |
| List configurations | `GET` | `/tls/configurations` |
| Get configuration | `GET` | `/tls/configurations/{tls_configuration_id}` |
| Update configuration | `PATCH` | `/tls/configurations/{tls_configuration_id}` |
Configurations apply to sets of IP pools and define HTTP protocols, TLS protocol versions, and the `bulk` flag for Platform TLS. **Always include `dns_records`** to get A/AAAA/CNAME records needed for DNS setup. Filter: `filter[bulk]`.
Typical configurations available on most accounts (IDs vary per account):
| Name | HTTP Protocols | TLS Protocols | Best For |
| ---------------------- | ------------------------ | ------------- | ----------------------------------- |
| TLS v1.3 | http/1.1, http/2 | 1.2, 1.3 | Standard setup (usually default) |
| TLS v1.3+0RTT | http/1.1, http/2 | 1.2, 1.3+0RTT | Lower latency (idempotent requests) |
| HTTP/3 & TLS v1.3 | http/1.1, http/2, http/3 | 1.2, 1.3 | Modern clients, best performance |
| HTTP/3 & TLS v1.3+0RTT | http/1.1, http/2, http/3 | 1.2, 1.3+0RTT | Maximum performance |
0-RTT (early data) improves latency but has replay risk for non-idempotent requests. HTTP/3 uses QUIC for better mobile/lossy-network performance. List your account's configs with `GET /tls/configurations`.
```bash
# Get config with DNS records for domain setup
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/tls/configurations/{tls_configuration_id}?include=dns_records"
# Response includes A records (for apex) and CNAME target (for subdomains)
```
## TLS Domains
| Action | Method | Endpoint |
| ------------ | ------ | -------------- |
| List domains | `GET` | `/tls/domains` |
Read-only view of all domains across certificates and subscriptions. Filters: `filter[in_use]`, `filter[tls_certificates.id]`, `filter[tls_subscriptions.id]`. Include: `tls_activations`, `tls_certificates`, `tls_subscriptions`.
```bash
# Check domain TLS status
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/tls/domains?filter[in_use]=true&include=tls_activations,tls_subscriptions"
```
## Mutual TLS
| Action | Method | Endpoint |
| ---------------------- | -------- | ---------------------------------------------------------------------------------- |
| List authentications | `GET` | `/tls/mutual_authentications` |
| Create authentication | `POST` | `/tls/mutual_authentications` |
| Get authentication | `GET` | `/tls/mutual_authentications/{mutual_authentication_id}` |
| Update authentication | `PATCH` | `/tls/mutual_authentications/{mutual_authentication_id}` |
| Delete authentication | `DELETE` | `/tls/mutual_authentications/{mutual_authentication_id}` |
| Set mTLS on activation | `PATCH` | `/tls/activations/{tls_activation_id}` (with `mutual_authentication` relationship) |
Upload a PEM-formatted CA `cert_bundle` for client certificate validation. `enforced: true` (default) fails closed; `enforced: false` fails open. Attach to a TLS activation by PATCHing the activation with a `mutual_authentication` relationship. Pass `null` ID to detach.
Requires existing server-side TLS (custom cert activation or Platform TLS subscription).
## Bulk Certificates (Platform TLS)
| Action | Method | Endpoint |
| ---------------- | -------- | ----------------------------------------- |
| List bulk certs | `GET` | `/tls/bulk/certificates` |
| Upload bulk cert | `POST` | `/tls/bulk/certificates` |
| Get bulk cert | `GET` | `/tls/bulk/certificates/{certificate_id}` |
| Update bulk cert | `PATCH` | `/tls/bulk/certificates/{certificate_id}` |
| Delete bulk cert | `DELETE` | `/tls/bulk/certificates/{certificate_id}` |
Requires both `cert_blob` and `intermediates_blob` (separate from Custom TLS which uses a single blob). Uploading automatically enables TLS for all SAN domains. Must associate with a `tls_configuration` (bulk type). Deployment averages 60 seconds, may take up to 1 hour.
## Certificate Signing Requests
| Action | Method | Endpoint |
| ---------- | ------ | ----------------------------------- |
| Create CSR | `POST` | `/tls/certificate_signing_requests` |
Generates a CSR with specified SANs. Key types: `RSA2048`, `ECDSA256`. Optionally reference an existing `tls_private_key`; otherwise Fastly generates one. Cannot specify both `key_type` and `tls_private_key`.
## How It Works
**Platform TLS**: Create subscription with domain(s) -> Fastly returns DNS challenges -> configure DNS -> DNS records are checked and Fastly procures cert -> auto-renews provided DNS is maintained. Challenge types: `managed-dns` (CNAME for ACME challenge), `managed-http-cname` (CNAME to Fastly), `managed-http-a` (A records for apex).
**Custom TLS**: Upload private key -> upload certificate -> create TLS activation linking cert + config + domain. You manage renewal.
**Bulk/Platform TLS Certificates**: Upload cert + intermediates -> Fastly auto-activates all SAN domains. Most specific hostname wins if certs overlap. You manage procurement and renewal.
**DNS setup**: Subdomains/wildcards use CNAME to the CNAME target from the configuration's `dns_records`. Apex domains use A records (AAAA for IPv6). Get the correct records from `GET /tls/configurations/{id}?include=dns_records`.
## Documentation
URLs below serve Markdown (use the `Accept: text/markdown` header).
| Source | URL |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| TLS product overview and prerequisites | `https://docs.fastly.com/products/tls-service-options` |
| TLS subscriptions API reference | `https://www.fastly.com/documentation/reference/api/tls/subs` |
| Custom certificates API reference | `https://www.fastly.com/documentation/reference/api/tls/custom-certs/certificates` |
| TLS activations API reference | `https://www.fastly.com/documentation/reference/api/tls/custom-certs/activations` |
| Private keys API reference | `https://www.fastly.com/documentation/reference/api/tls/custom-certs/private-keys` |
| Bulk certificates API reference | `https://www.fastly.com/documentation/reference/api/tls/platform` |
| Mutual TLS authentication API reference | `https://www.fastly.com/documentation/reference/api/tls/mutual-tls/authentication` |
| TLS security guides overview | `https://www.fastly.com/documentation/guides/security/tls` |
| TLS prerequisites and limitations | `https://www.fastly.com/documentation/guides/getting-started/domains/securing-domains/tls-prerequisites-and-limitations` |
| TLS dashboard overview | `https://www.fastly.com/documentation/guides/getting-started/domains/securing-domains/about-the-tls-dashboard` |
For general Fastly platform guidance, documentation source index, and other specialized skills, see the `fastly` skill.
SHA-256: e4aad0fd151bb181bd49c62573b6c651f29edd2a53c601e8bc77bfeed9c7def7