We've been making changes to how we organize and display our docs. Our work isn't done but we'd love your feedback.

Fastly offers an API for enabling TLS using certificates that are generated and managed by Fastly. Optionally, customers with access to multiple sets of IPs can apply different TLS configuration options to these TLS enabled domains.

TLS Subscriptions

The TLS subscriptions API allows you to programmatically generate and renew TLS certificates. Once a subscription is created for a given hostname or wildcard domain, DNS records are checked to ensure that the domain on the subscription is owned by the subscription creator. Provided DNS records are maintained, TLS certificates will automatically renew.

Fields

field type description
certificate_authority string

The entity that issues and certifies the TLS certificates for your subscription. Valid value is lets-encrypt.

created_at string

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

state string

The current state of your subscription. The list of possible states are: pending, processing, issued, and renewing. Read Only.

updated_at string

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

Actions

GET /tls/subscriptions

List all TLS subscriptions.

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 subscriptions per page.

include string

Include relationships. Optional, comma separated values. Permitted values: tls_authorizations,tls_certificates,tls_domains.

Request Example
GET /tls/subscriptions 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": "TLS_SUBSCRIPTION_ID",
      "type" : "tls_subscription",
      "attributes": {
        "state": "issued",
        "certificate_authority": "lets-encrypt",
        "created_at": "2019-02-07T12:12:12+00:00",
        "updated_at": "2019-02-07T12:12:12+00:00"
      },
      "relationships": {
        "tls_authorizations": {
          "data": [{
            "type": "tls_authorization",
            "id": "TLS_AUTHORIZATION_ID"
          }],
        },
        "tls_certificates": {
          "data": [{
            "type": "tls_certificate",
            "id": "TLS_CERTIFICATE_ID"
          }],
        },
        "tls_domains": {
          "data": [{
            "type": "tls_domain",
            "id": "DOMAIN_NAME"
          }],
        },
      }
    }
  ]
}
GET /tls/subscriptions/id

List a single TLS subscription.

Authentication

API token with at least TLS management permissions.

Parameters
parameter type description
include string

Include relationships. Optional, comma separated values. Permitted values: tls_authorizations,tls_certificates,tls_domains.

Request Example
GET /tls/subscriptions/: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": "TLS_SUBSCRIPTION_ID",
    "type" : "tls_subscription",
      "attributes": {
        "state": "issued",
        "certificate_authority": "lets-encrypt",
        "created_at": "2019-02-07T12:12:12+00:00",
        "updated_at": "2019-02-07T12:12:12+00:00"
    },
    "relationships": {
      "tls_authorizations": {
        "data": [{
          "type": "tls_authorization",
          "id": "TLS_AUTHORIZATION_ID"
        }],
      },
      "tls_certificates": {
        "data": [{
          "type": "tls_certificate",
          "id": "TLS_CERTIFICATE_ID"
        }],
      },
      "tls_domains": {
        "data": [{
          "type": "tls_domain",
          "id": "DOMAIN_NAME"
        }],
      },
    }
  }
}
POST /tls/subscriptions

Create a new TLS subscription. This returns a list of DNS records that are used to verify domain ownership.

Authentication

API token with at least TLS management permissions.

Request Example
POST /tls/subscriptions HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data" : {
    "type" : "tls_subscription",
    "attributes": {
      "certificate_authority": "lets-encrypt",
    },
    "relationships": {
      "tls_domains": {
        "data": [{
          "type": "tls_domain",
          "id": "DOMAIN_NAME"
        }],
      },
      "tls_configuration": {
        "data": {
         "type": "tls_configuration",
         "id": "TLS_CONFIGURATION_ID"
        }
      }
    }
  }
}
Response Example
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "TLS_SUBSCRIPTION_ID",
    "type" : "tls_subscription",
    "attributes": {
      "state": "pending",
      "certificate_authority": "lets-encrypt",
      "created_at": "2019-02-07T12:12:12+00:00",
      "updated_at": "2019-02-07T12:12:12+00:00"
    },
    "relationships": {
      "tls_authorizations": {
        "data": [{
          "type": "tls_authorization",
          "id": "TLS_AUTHORIZATION_ID"
        }],
      },
      "tls_certificates": {
        "data": [],
      },
      "tls_domains": {
        "data": [{
          "type": "tls_domain",
          "id": "DOMAIN_NAME"
        }],
      },
    }
  },
  "included": [{
    "id": "TLS_AUTHORIZATION_ID",
    "type": "tls_authorization",
    "attributes": {
      "challenges": [{
        "type": "managed-dns",
        "record_type": "CNAME",
        "record_name": "ACME_CHALLENGE_HOSTNAME",
        "values": [
          "FASTLY_VALIDATION_HOSTNAME"
        ],
        "instructions": "create a CNAME record for ACME_CHALLENGE_HOSTNAME and point it to FASTLY_VALIDATION_HOSTNAME."
      },
        "type": "managed-http-cname",
        "record_type": "CNAME",
        "record_name": "DOMAIN_NAME",
        "values": [
          "FASTLY_VALIDATION_HOSTNAME"
        ],
        "instructions": "create a CNAME record for DOMAIN_NAME and point it to FASTLY_VALIDATION_HOSTNAME."
      },
        "type": "managed-http-a",
        "record_type": "A",
        "record_name": "DOMAIN_NAME",
        "values": [
          "FASTLY_IP_ADDRESSES"
        ],
        "instructions": "create 4 A records for DOMAIN_NAME and point them to FASTLY_IP_ADDRESSES."
      }],
      "created_at": "2019-02-07T12:12:12+00:00",
      "state": "pending",
      "updated_at": "2019-02-07T12:12:12+00:00",
      "warnings": null
    }
  }]
}
DELETE /tls/subscriptions/id

Destroy a TLS subscription. A subsctiption cannot be destroyed if there are domains in the TLS enabled state.

Authentication

API token with at least TLS management permissions.

Request Example
DELETE /tls/subscriptions/TLS_SUBSCRIPTION_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 Configurations

Customers with access to multiple sets of IP pools are able to apply different configuration options to their TLS enabled domains.

Fields

field type description
created_at string

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

default boolean

Signifies whether or not Fastly will use this configuration as a default when creating a new TLS Activation. Read Only.

http_protocols array

HTTP protocols available on your configuration. Read Only.

name string

A custom name for your TLS configuration.

relationships.service -

Object. The Fastly Service that is automatically selected when this TLS Configuration is used. Read Only.

relationships.dns_records -

Object. The DNS records to use for this configuration.

tls_protocols array

TLS protocols available on your configuration. Read Only.

updated_at string

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

Actions

GET /tls/configurations

List all TLS configurations.

Authentication

API token with at least TLS management permissions.

Parameters
parameter type description
include string

Include related objects. Optional, comma-separated values. Permitted values: dns_records.

page[number] integer

The page index for pagination.

page[size] integer

The number of configurations per page.

Request Example
GET /tls/configurations?include=dns_records HTTP/1.1
Accept: application/vnd.api+json
Fastly-Key: YOUR_FASTLY_TOKEN
Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": [
    {
      "id": "TLS_CONFIGURATION_ID",
      "type": "tls_configuration",
      "attributes": {
        "created_at": "2019-02-01T12:12:12.000Z",
        "default": true,
        "http_protocols": [
          "http/1.1",
          "http/2"
        ],
        "name": "TLS Configuration A",
        "tls_protocols": [
          "1.1",
          "1.2"
        ],
        "updated_at": "2019-02-01T12:12:12.000Z"
      },
      "relationships": {
        "dns_records": {
          "data": [
            { "id": "2a04:4e42::645", "type": "dns_record" },
            { "id": "151.101.2.133", "type": "dns_record" },
            { "id": "2a04:4e42:200::645", "type": "dns_record" },
            { "id": "151.101.66.133", "type": "dns_record" },
            { "id": "2a04:4e42:600::645", "type": "dns_record" },
            { "id": "151.101.194.133", "type": "dns_record" },
            { "id": "2a04:4e42:400::645", "type": "dns_record" },
            { "id": "151.101.130.133", "type": "dns_record" },
            { "id": "2a04:4e42:fd8::645", "type": "dns_record" },
            { "id": "199.232.198.133", "type": "dns_record" },
            { "id": "2a04:4e42:fd9::645", "type": "dns_record" },
            { "id": "199.232.194.133", "type": "dns_record" },
            { "id": "d.sni.global.fastly.net", "type": "dns_record" },
            { "id": "d.sni.us-eu.fastly.net", "type": "dns_record" }
          ]
        },
        "service": {
          "data": {
            "id": "SERVICE_ID",
            "type": "service"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "2a04:4e42::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "global" }
    },
    {
      "id": "151.101.2.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "global" }
    },
    {
      "id": "2a04:4e42:200::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "global" }
    },
    {
      "id": "151.101.66.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "global" }
    },
    {
      "id": "2a04:4e42:600::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "global" }
    },
    {
      "id": "151.101.194.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "global" }
    },
    {
      "id": "2a04:4e42:400::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "global" }
    },
    {
      "id": "151.101.130.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "global" }
    },
    {
      "id": "2a04:4e42:fd8::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "mbz100" }
    },
    {
      "id": "199.232.198.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "mbz100" }
    },
    {
      "id": "2a04:4e42:fd9::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "mbz100" }
    },
    {
      "id": "199.232.194.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "mbz100" }
    },
    {
      "id": "d.sni.global.fastly.net",
      "type": "dns_record",
      "attributes": { "record_type": "CNAME", "region": "global" }
    },
    {
      "id": "d.sni.us-eu.fastly.net",
      "type": "dns_record",
      "attributes": { "record_type": "CNAME", "region": "us-eu" }
    }
  ],
  "links": {
    "self": "http://example.org/tls/configurations?include=dns_records&page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "first": "http://example.org/tls/configurations?include=dns_records&page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "prev": null,
    "next": null,
    "last": "http://example.org/tls/configurations?include=dns_records&page%5Bnumber%5D=1&page%5Bsize%5D=100"
  },
  "meta": {
    "per_page": 100,
    "current_page": 1,
    "record_count": 1,
    "total_pages": 1
  }
}
GET /tls/configurations/TLS_CONFIGURATION_ID

List one TLS configuration.

Authentication

API token with at least TLS management permissions.

Parameters
parameter type description
include string

Include related objects. Optional, comma-separated values. Permitted values: dns_records.

Request Example
GET /tls/configurations/TLS_CONFIGURATION_ID?include=dns_records HTTP/1.1
Accept: application/vnd.api+json
Fastly-Key: YOUR_FASTLY_TOKEN
Response Example
HTTP/1.1 200 OK
Content-Type: text/html;charset=utf-8
{
  "data": {
    "id": "TLS_CONFIGURATION_ID",
    "type": "tls_configuration",
    "attributes": {
      "created_at": "2019-02-01T12:12:12.000Z",
      "default": true,
      "http_protocols": [
        "http/1.1",
        "http/2"
      ],
      "name": "TLS Configuration A",
      "tls_protocols": [
        "1.1",
        "1.2"
      ],
      "updated_at": "2019-02-01T12:12:12.000Z"
    },
    "relationships": {
      "dns_records": {
        "data": [
          {
            "id": "2a04:4e42::645",
            "type": "dns_record"
          },
          {
            "id": "151.101.2.133",
            "type": "dns_record"
          },
          {
            "id": "2a04:4e42:200::645",
            "type": "dns_record"
          },
          {
            "id": "151.101.66.133",
            "type": "dns_record"
          },
          {
            "id": "2a04:4e42:600::645",
            "type": "dns_record"
          },
          {
            "id": "151.101.194.133",
            "type": "dns_record"
          },
          {
            "id": "2a04:4e42:400::645",
            "type": "dns_record"
          },
          {
            "id": "151.101.130.133",
            "type": "dns_record"
          },
          {
            "id": "2a04:4e42:fd8::645",
            "type": "dns_record"
          },
          {
            "id": "199.232.198.133",
            "type": "dns_record"
          },
          {
            "id": "2a04:4e42:fd9::645",
            "type": "dns_record"
          },
          {
            "id": "199.232.194.133",
            "type": "dns_record"
          },
          {
            "id": "d.sni.global.fastly.net",
            "type": "dns_record"
          },
          {
            "id": "d.sni.us-eu.fastly.net",
            "type": "dns_record"
          }
        ]
      },
      "service": {
        "data": {
          "id": "SERVICE_ID",
          "type": "service"
        }
      }
    }
  },
  "included": [
    {
      "id": "2a04:4e42::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "global" }
    },
    {
      "id": "151.101.2.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "global" }
    },
    {
      "id": "2a04:4e42:200::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "global" }
    },
    {
      "id": "151.101.66.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "global" }
    },
    {
      "id": "2a04:4e42:600::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "global" }
    },
    {
      "id": "151.101.194.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "global" }
    },
    {
      "id": "2a04:4e42:400::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "global" }
    },
    {
      "id": "151.101.130.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "global" }
    },
    {
      "id": "2a04:4e42:fd8::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "mbz100" }
    },
    {
      "id": "199.232.198.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "mbz100" }
    },
    {
      "id": "2a04:4e42:fd9::645",
      "type": "dns_record",
      "attributes": { "record_type": "AAAA", "region": "mbz100" }
    },
    {
      "id": "199.232.194.133",
      "type": "dns_record",
      "attributes": { "record_type": "A", "region": "mbz100" }
    },
    {
      "id": "d.sni.global.fastly.net",
      "type": "dns_record",
      "attributes": { "record_type": "CNAME", "region": "global" }
    },
    {
      "id": "d.sni.us-eu.fastly.net",
      "type": "dns_record",
      "attributes": { "record_type": "CNAME", "region": "us-eu" }
    }
  ]
}
PATCH /tls/configurations/id

Update a TLS configuration

Authentication

API token with at least TLS management permissions.

Request Example
PATCH /tls/configurations/:id HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data" : {
    "id": "TLS_CONFIGURATION_ID",
    "type" : "tls_configuration",
    "attributes": {
      "name": "New TLS configuration name"
    }
  }
}
Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "TLS_CONFIGURATION_ID",
    "type": "tls_configuration",
    "attributes": {
      "created_at": "2019-02-01T12:12:12.000Z",
      "default": true,
      "http_protocols": [
        "http/1.1",
        "http/2"
      ],
      "name": "New TLS configuration name",
      "tls_protocols": [
        "1.1",
        "1.2"
      ],
      "updated_at": "2019-02-01T12:12:12.000Z"
    },
  }
}