---
title: TLS Subscriptions
summary: The TLS subscriptions API allows you to programmatically generate TLS certificates that are procured and renewed by Fastly. 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. If Fastly is unable to issue a certificate, we will retry to issue the certificate for 7 days past subscription creation or the latest certificate's not_after date, whichever is later. If after 7 days Fastly is unable to issue a certificate, the subscription state will change to <code>failed</code> and Fastly will stop retrying.
url: https://www.fastly.com/documentation/reference/api/tls/subs
---

The TLS subscriptions API allows you to programmatically generate TLS certificates that are procured and renewed by Fastly. 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. If Fastly is unable to issue a certificate, we will retry to issue the certificate for 7 days past subscription creation or the latest certificate's not_after date, whichever is later. If after 7 days Fastly is unable to issue a certificate, the subscription state will change to <code>failed</code> and Fastly will stop retrying.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `certificate_authority` | string | The entity that issues and certifies the TLS certificates for your subscription, either <code>certainly</code>, <code>lets-encrypt</code>, or <code>globalsign</code>. To migrate the subscription from one certificate authority to another, such as to migrate from 'lets-encrypt' to 'certainly',  pass <code>certificate_authority</code> to the PATCH endpoint. To migrate from 'globalsign' to 'certainly', contact Fastly Support. |
| `relationships.common_name.id` | string | The domain name. |
| `relationships.tls_certificates.id` | string | Alphanumeric string identifying a TLS certificate. |
| `relationships.tls_configuration.id` | string | Alphanumeric string identifying a TLS configuration. |
| `relationships.tls_domains.id` | string | The domain name. |
| `type` | string | Resource type. |
| `created_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `deleted_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `has_active_order` | boolean | Subscription has an active order. |
| `id` | string | Alphanumeric string identifying a TLS subscription. (Read-only) |
| `state` | string | The current state of your subscription. |
| `updated_at` | string | Date and time in ISO 8601 format. (Read-only) |

## API endpoints

### List TLS subscriptions

**GET** `/tls/subscriptions`

List all TLS subscriptions.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `filter[certificate_authority]` | string | query | No | Limit the returned subscriptions to a specific certification authority. Values may include <code>certainly</code>, <code>lets-encrypt</code>, or <code>globalsign</code>. |
| `filter[has_active_order]` | boolean | query | No | Limit the returned subscriptions to those that have currently active orders. Permitted values: <code>true</code>. |
| `filter[state]` | string | query | No | Limit the returned subscriptions by state. Valid values are <code>pending</code>, <code>processing</code>, <code>issued</code>, <code>renewing</code>, and <code>failed</code>. Accepts parameters: <code>not</code> (e.g., <code>filter[state][not]=renewing</code>). |
| `filter[tls_domains.id]` | string | query | No | Limit the returned subscriptions to those that include the specific domain. |
| `include` | string | query | No | Include related objects. Optional, comma-separated values. Permitted values: <code>tls_authorizations</code>, <code>tls_authorizations.globalsign_email_challenge</code>, <code>tls_authorizations.self_managed_http_challenge</code>, and <code>tls_certificates</code>. |
| `page[number]` | integer | query | No | Current page. |
| `page[size]` | integer | query | No | Number of records per page. |
| `sort` | string | query | No | The order in which to list the results. |

### Create a TLS subscription

**POST** `/tls/subscriptions`

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

### Get a TLS subscription

**GET** `/tls/subscriptions/{tls_subscription_id}`

Show a TLS subscription.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `include` | string | query | No | Include related objects. Optional, comma-separated values. Permitted values: <code>tls_authorizations</code>, <code>tls_authorizations.globalsign_email_challenge</code>, <code>tls_authorizations.self_managed_http_challenge</code>, and <code>tls_certificates</code>. |
| `tls_subscription_id` | string | path | Yes | Alphanumeric string identifying a TLS subscription. |

### Delete a TLS subscription

**DELETE** `/tls/subscriptions/{tls_subscription_id}`

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

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `tls_subscription_id` | string | path | Yes | Alphanumeric string identifying a TLS subscription. |

### Update a TLS subscription

**PATCH** `/tls/subscriptions/{tls_subscription_id}`

Change the TLS domains or common name associated with this subscription, update the TLS configuration for this set of domains, or retry a subscription with state <code>failed</code> by setting the state to <code>retry</code>.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `force` | boolean | query | No | A flag that allows you to edit and delete a subscription with active domains. Valid to use on PATCH and DELETE actions. As a warning, removing an active domain from a subscription or forcing the deletion of a subscription may result in breaking TLS termination to that domain. |
| `tls_subscription_id` | string | path | Yes | Alphanumeric string identifying a TLS subscription. |

### Creates a GlobalSign email challenge

**POST** `/tls/subscriptions/{tls_subscription_id}/authorizations/{tls_authorization_id}/globalsign_email_challenges`

Creates an email challenge for a domain on a GlobalSign subscription. An email challenge will generate an email that can be used to validate domain ownership. If this challenge is created, then the domain can only be validated using email for the given subscription.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `tls_authorization_id` | string | path | Yes | Alphanumeric string identifying a TLS subscription. |
| `tls_subscription_id` | string | path | Yes | Alphanumeric string identifying a TLS subscription. |

### Delete a GlobalSign email challenge

**DELETE** `/tls/subscriptions/{tls_subscription_id}/authorizations/{tls_authorization_id}/globalsign_email_challenges/{globalsign_email_challenge_id}`

Deletes a GlobalSign email challenge. After a GlobalSign email challenge is deleted, the domain can use HTTP and DNS validation methods again.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `globalsign_email_challenge_id` | string | path | Yes | Alphanumeric string identifying a GlobalSign email challenge. |
| `tls_authorization_id` | string | path | Yes | Alphanumeric string identifying a TLS subscription. |
| `tls_subscription_id` | string | path | Yes | Alphanumeric string identifying a TLS subscription. |