On this page

Custom Domains

Introduction

What are Custom Domains?

A Custom Domain is user-defined URL that replaces the default Qencode URL provided by the Media Storage and Live Streaming services. This allows you to map your domain, like www.yourdomain.com, to your cloud storage bucket or live stream URL.

Using Signed URLs with the Custom Domain is available as an option. You can use it in case you want to protect the content from unsolicited access. More details in Signed URLs tutorial.

Why Use Custom Domains

Brand Recognition: Using a unique URL for your streams and VOD content improves brand awareness and perception.
Control and Flexibility: you have full control over the domain, which means you can decide on the domain's structure, subdomains, and any associated SEO strategies.

Pre-requisites

Before you can activate and utilize the custom user domain feature, please ensure that:

You are the owner of the domain you wish to use.
You have full access to the DNS settings of said domain. This access is essential, as you will need to make specific changes to the domain's DNS records to properly configure and integrate it with our media storage solution.

If you don't have a domain yet or are unsure about your DNS access, please consult your domain provider or IT department for assistance.

1. Create a Custom Domain

Portal instructions

Navigate to the Domain Management page in the Content Delivery section.
Click on Create domain and enter the custom domain you want to use

Make sure to input a valid Fully Qualified Domain Name (FQDN), like subdomain.youromain.com.

Select your preferred domain type.

Media Storage: Used to create Custom Domains for Media Storage buckets.
Live Streaming: Used to create Custom Domains for Live Streaming Playback URLs.

Creating a domain

API instructions

POST /v1/domains

You can create custom domains and use them for live-streaming or media storage playback.

Request Example:

curl -X POST 'https://api-cdn.qencode.com/v1/domains' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN' \ 
-H 'Content-Type: application/json' \ 
--data-raw '{"name": "live.mydomain.com", "type": "live"}'

The request returns the object containing all of the attributes of your domain.

Response Example:

{
    "domain": {
        "created": "2023-06-07 14:17:25",
        "id": "aeac03d6-beb0-4638-a094-fbc35653f931",
        "type": "live",
        "domain_name": "live.mydomain.com"
    }
}

GET /v1/domains

Gets a list of user domains.

Request Example:

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
-X GET https://api-cdn.qencode.com/v1/domains

The request returns the list of domain objects.

Response Example:

{
    "domains": [
        {
            "created": "2023-06-07 14:17:25",
            "id": "aeac03d6-beb0-4638-a094-fbc35653f931",
            "type": "live",
            "domain_name": "live.mydomain.com"
        }
    ]
}

GET /v1/domains/<domain_id>

Gets a playback domain information.

Request Example:

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
-X GET https://api-cdn.qencode.com/v1/domains/$DOMAIN_ID

The request returns the object containing all of the attributes of your domain.

Response Example:

{
    "domain": {
        "created": "2023-06-07 14:17:25",
        "id": "aeac03d6-beb0-4638-a094-fbc35653f931",
        "type": "live",
        "domain_name": "live.mydomain.com"
    }
}

DELETE /v1/domains/<domain_id>

Deletes a playback domain.

Request Example:

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
-X DELETE https://api-cdn.qencode.com/v1/domains/$DOMAIN_ID

The request returns the operation status.

Response Example:

{
    "status": "ok"
}

2. Verify your Domain

Portal instructions

Follow the on-screen prompts to verify your Custom Domain.
Ensure the domain's status transitions from 'Pending' to 'Issued'.

API instructions

POST /v1/tls/subscriptions

To initiate a TLS subscription

Request Example:

curl -X POST 'https://api-cdn.qencode.com/v1/tls/subscriptions' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN' \ 
-H 'Content-Type: application/json' \ 
--data-raw '{"domain_id": "aeac03d6-beb0-4638-a094-fbc35653f931"}'

The request returns the object containing all of the TLS subscription attributes.

Response Example:

{
  "tls_subscription": {
    "status": "pending",
    "created": "2023-06-12 15:10:48",
    "domain_id": "aeac03d6-beb0-4638-a094-fbc35653f931",
    "message": "TLS subscription created. You should verify your domain ownership. 
    Create a CNAME for 'live.mydomain.com' and point it to 'j.sni.global.fastly.net.'.",
    "id": "7d819560-6220-4b76-bf9a-3784a64ac7ff"
  }
}

GET /v1/tls/subscriptions

To view all TLS subscriptions related to your domains

Request Example:

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-cdn.qencode.com/v1/tls/subscriptions

Response Example:

{
  "tls_subscriptions": [
      {
          "status": "pending",
          "created": "2023-06-12 15:10:48",
          "tls_subscription_id": "3WrHK1GCLSN4AZIHqQw81A",
          "id": "7d819560-6220-4b76-bf9a-3784a64ac7ff",
          "domain_id": "aeac03d6-beb0-4638-a094-fbc35653f931"
      }
  ]
}

GET /v1/tls/subscriptions/<tls_subscription_id>

To obtain details of a specific TLS subscription

Request Example:

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-cdn.qencode.com/v1/tls/subscriptions/$TLS_SUBSCRIPTION_ID

The request returns the object containing all of the attributes of your TLS subscription.

Response Example:

{
  "tls_subscription": {
    "status": "pending",
    "created": "2023-06-12 15:10:48",
    "domain_id": "aeac03d6-beb0-4638-a094-fbc35653f931",
    "id": "7d819560-6220-4b76-bf9a-3784a64ac7ff"
  }
}

DELETE /v1/tls/subscriptions/<tls_subscription_id>

To remove a TLS subscription

Request Example:

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X DELETE https://api-cdn.qencode.com/v1/tls/subscriptions/$TLS_SUBSCRIPTION_ID

The request returns the deleting operation status.

Response Example:

{
  "status": "ok"
}

3. Accessing Content via Custom Domain

For example, the content is saved in Qencode Media Storage with the following file structure: the list of files and folders inside the bucket. There is a possibility to copy URL for each file.

Here's the structure of the URLs used to access data in your bucket not using a custom domain:

https://$BUCKET.media-storage.$REGION.qencode.com/path/to/video.mp4

Example: URL to access “file1” without custom domain:

https://my-qencode-bucket.media-storage.us-west.qencode.com/file1

Here's the structure of the URLs used to access data in your bucket using a custom domain:

https://$CUSTOM_DOMAIN/path/to/video.mp4

Example: URL to access “file1” using "yourdomain.com" custom domain:

https://yourdomain.com/file1

Troubleshooting Tips

Domain Status Problems: Ensure proper TLS certificate configuration.
Content Accessibility Issues: Review domain linkage and activation process.
Token-Related Problems: Check token's validity or consider its regeneration.
Domain or Key Input Issues: Confirm accurate input and system operations.

Best Practices

Adopt transparent domain and key naming methods.
Guard your TLS certificates and signing keys diligently.
Keep an eye on domain statuses routinely.

API Integration

For domain management:

POST /v1/domains - to create a domain
GET /v1/domains - to retrieve a list of your domains
GET /v1/domains/<domain_id> - to fetch specific domain details
DELETE /v1/domains/<domain_id> - to erase a domain

For TLS domain subscriptions:

POST /v1/tls/subscriptions - to initiate a TLS subscription
GET /v1/tls/subscriptions - to view all TLS subscriptions related to your domains
GET /v1/tls/subscriptions/<tls_subscription_id> - to obtain details of a specific TLS subscription
DELETE /v1/tls/subscriptions/<tls_subscription_id> - to remove a TLS subscription

Known Limitations

At this moment, when using custom domains with our media storage solution, your TLS (Transport Layer Security) subscription will be based on Let's Encrypt.

Please be aware of the following considerations:

We currently do not support the integration of custom TLS certificates.
However, we're excited to announce that support for custom TLS certificates is on the horizon. This upcoming feature will offer you more flexibility in managing your domain's security.

Further Support

For additional guidance or help, consult the Qencode Documentation or contact Qencode Support via support@qencode.com.