Custom Domains

Introduction

What are Custom Domains?

A Custom Domain is a 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.

Signed URLs can also be used with a Custom Domain to protect content from unauthorized access. Learn more in our 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

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"}'

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

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

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

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

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

curl -X PUT https://api-cdn.qencode.com/v1/domains/$DOMAIN_ID 
-H 'Authorization: Bearer $ACCESS_TOKEN'  
-H 'Content-Type: application/json'  
--data-raw '{"bucket_name": "new-bucket-name"}'

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

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

{
    "status": "ok"
}

1. Navigate to the Domains page in the Content Delivery section.
2. 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 yourdomain.com.
3. 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.

2

Verify your Domain

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"}'

{
  "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"
  }
}

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

{
  "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"
      }
  ]
}

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

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

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

{
    "status": "ok"
}

1. Follow the on-screen prompts to verify your Custom Domain.

2. Ensure the domain's status transitions from 'Pending' to 'Issued'.

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
• PUT /v1/domains/<domain_id> - to update vod domain
• 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.

Need More Help?

For additional information, tutorials, or support, visit the Qencode Documentation page or contact Qencode Support at support@qencode.com.