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 this 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

This method allows you to register a new custom domain for streaming or VOD playback. You provide a domain name and its type, and the system will associate it with your Qencode environment. This is typically used to replace the default Qencode URL with your branded 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"
    }
}

You can retrieve a list of all your registered custom domains using this method. It returns metadata for each domain such as creation date, type, domain and bucket name. This is helpful for reviewing and managing your existing configurations.

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

This method fetches detailed information about a single custom domain using its unique ID. It's useful when you need to inspect or verify domain settings individually.

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

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

This method initiates a TLS subscription to enable secure HTTPS access via your custom domain. It generates a unique CNAME record and provides instructions for DNS verification. The domain must be verified through this DNS step to complete the HTTPS setup.

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

This method retrieves a list of all TLS subscriptions associated with your account. Each entry includes its creation time, status, and the domain it belongs to.

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

Use this method to fetch detailed information about a single TLS subscription by its ID. This is useful for checking its status and verifying the DNS configuration is in place.

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

This method removes a TLS subscription from your account. This is typically used when you no longer need the domain to support HTTPS, or if you plan to reconfigure the verification process from scratch.

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

4

Manage Existing Domains

You can use this method to update an existing custom domain, such as linking it to a different storage bucket. Only bucket name can be updated, and the domain must already exist in your Qencode account.

You can update a domain’s properties, but only for media storage domains that are associated with a bucket.

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

Note

This endpoint can only be used to update domains that are linked to a storage bucket. Live-streaming domains cannot be updated using this method.

This method deletes an existing custom domain from your Qencode environment. Once deleted, the domain will no longer be available for use in content delivery or playback.

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

{
    "status": "ok"
}

1. Click the options button next to the domain you want to edit and select Update. Pay attention that Update option will be available only for domains with Media Storage type.

2. On the Edit Domain modal, select the required bucket from the dropdown list.

3. Click Update to apply the changes.

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.