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
include string

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

page[number] integer

The page index for pagination.

page[size] integer

The number of subscriptions per page.

Request Example
GET /tls/subscriptions 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_SUBSCRIPTION_ID",
      "type": "tls_subscription",
      "attributes": {
        "certificate_authority": "lets-encrypt",
        "created_at": "2019-02-01T12:12:12.000Z",
        "state": "issued",
        "updated_at": "2019-02-01T12:12:12.000Z"
      },
      "relationships": {
        "tls_authorizations": {
          "data": [
            { "id": "TLS_AUTHORIZATION_ID", "type": "tls_authorization" }
          ]
        },
        "tls_certificates": {
          "data": [
            { "id": "TLS_CERTIFICATE_ID", "type": "tls_certificate" }
          ]
        },
        "tls_domains": {
          "data": [
            { "id": "DOMAIN_NAME", "type": "tls_domain" }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://api.fastly.com/tls/subscriptions?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "first": "https://api.fastly.com/tls/subscriptions?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "prev": null,
    "next": null,
    "last": "https://api.fastly.com/tls/subscriptions?page%5Bnumber%5D=1&page%5Bsize%5D=100"
  },
  "meta": { "per_page": 100, "current_page": 1, "record_count": 1, "total_pages": 1 }
}
GET /tls/subscriptions/id

Show a TLS subscription.

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

Request Example
GET /tls/subscriptions/:id?include=tls_authorizations 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_SUBSCRIPTION_ID",
    "type": "tls_subscription",
    "attributes": {
      "certificate_authority": "lets-encrypt",
      "created_at": "2019-02-01T12:12:12.000Z",
      "state": "issued",
      "updated_at": "2019-02-01T12:12:12.000Z"
    },
    "relationships": {
      "tls_authorizations": {
        "data": [
          { "id": "TLS_AUTHORIZATION_ID", "type": "tls_authorization" }
        ]
      },
      "tls_certificates": {
        "data": [
          { "id": "TLS_CERTIFICATE_ID", "type": "tls_certificate" }
        ]
      },
      "tls_domains": {
        "data": [
          { "id": "DOMAIN_NAME", "type": "tls_domain" }
        ]
      }
    }
  },
  "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" ]
          },
          {
            "type": "managed-http-cname",
            "record_type": "CNAME",
            "record_name": "DOMAIN_NAME",
            "values": [ "FASTLY_CNAME" ]
          },
          {
            "type": "managed-http-a",
            "record_type": "A",
            "record_name": "DOMAIN_NAME",
            "values": [ "FASTLY_IP_ADDRESSES" ]
          }
        ],
        "created_at": "2019-02-01T12:12:12.000Z",
        "state": "passing",
        "updated_at": "2019-02-01T12:12:12.000Z",
        "warnings": null
      }
    }
  ]
}
POST /tls/subscriptions

Create a new TLS subscription. This response includes a list of possible challenges to verify domain ownership.

Authentication

API token with at least TLS management permissions.

Request Example
POST /tls/subscriptions HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Fastly-Key: YOUR_FASTLY_TOKEN
{
  "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": {
      "certificate_authority": "lets-encrypt",
      "created_at": "2019-02-01T12:12:12.000Z",
      "state": "pending",
      "updated_at": "2019-02-01T12:12:12.000Z"
    },
    "relationships": {
      "tls_authorizations": {
        "data": [
          { "id": "TLS_AUTHORIZATION_ID", "type": "tls_authorization" }
        ]
      },
      "tls_certificates": {
        "data": [ ]
      },
      "tls_domains": {
        "data": [
          { "id": "DOMAIN_NAME", "type": "tls_domain" }
        ]
      }
    }
  },
  "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" ]
          },
          {
            "type": "managed-http-cname",
            "record_type": "CNAME",
            "record_name": "DOMAIN_NAME",
            "values": [ "FASTLY_CNAME" ]
          },
          {
            "type": "managed-http-a",
            "record_type": "A",
            "record_name": "DOMAIN_NAME",
            "values": [ "FASTLY_IP_ADDRESSES" ]
          }
        ],
        "created_at": "2019-02-01T12:12:12.000Z",
        "state": "pending",
        "updated_at": "2019-02-01T12:12:12.000Z",
        "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/:id HTTP/1.1
Accept: application/vnd.api+json
Fastly-Key: YOUR_FASTLY_TOKEN
Response Example
HTTP/1.1 204 No Content