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