Configure and use secure token

Secure token restricts content access to URLs that contain a valid MD5 hash and a Unix expiration timestamp. The CDN rejects requests with a missing, expired, or incorrect hash with a 403 Forbidden response.

Configure secure token in the Customer Portal

Log in to the Gcore Customer Portal and navigate to CDN > CDN resources. Open the resource.
On the OPTIONS tab, navigate to Access > Secure token.
Turn on Enable secure token.
In the Enter a key field, enter a key of 6–32 characters. This key is used in the hash formula on the origin server.
To allow access from any IP address, leave Add a client’s IP to the token unchecked. To restrict access to a single IP address, check it — the allowlisted IP is added to the hash formula in the generation scripts. Enterprise customers with mobile audiences have an IP binding mode that ties tokens to a subnet rather than a single IP.
Click Save changes.

Enabling secure token may decrease the cache hit ratio. To improve it, enable Ignore Query String, which treats objects with different query parameters as one cacheable object.

Set up token generation on the origin server

On the origin server, add a script that generates signed links for protected content. Each generated link must follow this format:

http://cdn.example.com/photo.jpeg?md5=DMF1ucDxtHCxwYQ&expires=2147483647

Where:

http://cdn.example.com/photo.jpeg is the path to the file
DMF1ucDxtHCxwYQ is the MD5 hash of {expires}{path}{ip} {key} (base64-encoded, URL-safe)
2147483647 is the expiration time in Unix timestamp format

The link generation scripts below contain ready-to-use PHP, Python, and OpenSSL examples. On the origin server, block direct client access to the origin — restricting inbound connections to CDN server IP ranges is one approach. The CDN validates the token at the edge before forwarding the request to the origin, so the origin does not need to perform token validation and must remain reachable by CDN servers without a token.

Secure token URL matching

Secure token validates three things from the request URL:

md5: the token hash
expires: the Unix timestamp until which the URL is valid
Path: the file path or directory path used when the token was generated

The path is important. The CDN recomputes the hash using the path that was used to generate the token, not necessarily the full requested path:

If the token was generated for an exact file path (e.g. /images/poster.jpeg), the CDN computes the hash with that same path on every request. Only requests for that exact file pass.
If the token was generated for a directory path ending with / (e.g. /videos/video-1/), the CDN computes the hash using the directory component of the requested path. A request for /videos/video-1/segment-001.ts uses /videos/video-1/ as the path in the hash and passes. A request for /videos/video-1/360p/segment.ts uses /videos/video-1/360p/ as the directory component — that does not match the token generated for /videos/video-1/, so it returns 403 Forbidden.

Query String Forwarding is a separate mechanism that copies md5 and expires from playlist body links to the actual media segment requests. It allows a player to receive the token with the master manifest and automatically propagate it to nested requests, each of which is still individually validated against the token path.

Token for exact file

Use an exact file token for standalone files — images, archives, MP4 files, or a single protected video manifest — when nested requests do not need to be authorized with the same token. Example protected file:

/images/poster.jpeg

Generate the token with this path:

/images/poster.jpeg

The user requests:

https://cdn.example.com/images/poster.jpeg?md5=TOKEN&expires=1777545540

This token is valid only for /images/poster.jpeg. It does not provide access to adjacent files:

https://cdn.example.com/images/poster.webp      → 403 Forbidden
https://cdn.example.com/images/poster.png       → 403 Forbidden
https://cdn.example.com/images/master.m3u8      → 403 Forbidden

Protect HLS and MPEG-DASH content

Use a token with Query String Forwarding enabled for HLS and MPEG-DASH when the player must request a master manifest, nested rendition manifests, media segments, and subtitles under the same path. In this mode, generate the token for the full directory path only — not for a filename. For the files in:

/videos/video-1/

use this path in the token generation script: For PHP:

$path = '/videos/video-1/';

For Python:

path = "/videos/video-1/"

This token works only for files directly inside /videos/video-1/. It does not work for files in subdirectories — /videos/video-1/360p/ for instance. If HLS or MPEG-DASH files are split across subdirectories, generate tokens for those directories separately or place the related manifests and segments under one directory. Example HLS files:

/videos/video-1/master.m3u8
/videos/video-1/rendition-1080.m3u8
/videos/video-1/segment-001.ts
/videos/video-1/segment-002.ts

Generate the token with the directory path:

/videos/video-1/

The user requests only the master manifest with the token:

https://cdn.example.com/videos/video-1/master.m3u8?md5=TOKEN&expires=1893456000

With Query String Forwarding enabled, the CDN automatically inserts the same query parameters into related manifest body links. The video player then requests nested files with the forwarded token:

https://cdn.example.com/videos/video-1/rendition-1080.m3u8?md5=TOKEN&expires=1893456000
https://cdn.example.com/videos/video-1/segment-001.ts?md5=TOKEN&expires=1893456000
https://cdn.example.com/videos/video-1/segment-002.ts?md5=TOKEN&expires=1893456000

For HLS and MPEG-DASH, configure Query String Forwarding with:

{
  "forward_from_file_types": [
    "m3u8",
    "mpd"
  ],
  "forward_to_file_types": [
    "ts",
    "mp4",
    "m3u8",
    "m4s",
    "vtt"
  ],
  "forward_only_keys": [
    "md5",
    "expires"
  ]
}

To check how Query String Forwarding works in real life, open this demo HLS manifest:

manifest URL: master.m3u8
hls.js player demo: master.m3u8

It will open the master file with nested files (note that &other=parameter is not forwarded):

http://demo-files-protected.gvideo.io/coffee_run/master.m3u8?md5=eBx15p01_a9JNuo1iZpTfQ&expires=1893456000&other=parameter
http://demo-files-protected.gvideo.io/coffee_run/index-svod720n-v1-a1.m3u8?expires=1893456000&md5=eBx15p01_a9JNuo1iZpTfQ
http://demo-files-protected.gvideo.io/coffee_run/segment-1-svod720n-v1-a1.ts?expires=1893456000&md5=eBx15p01_a9JNuo1iZpTfQ
http://demo-files-protected.gvideo.io/coffee_run/segment-2-svod720n-v1-a1.ts?expires=1893456000&md5=eBx15p01_a9JNuo1iZpTfQ

Token in a path

Tokens embedded into the URL path are not supported for CDN natively. This option is available for Gcore Video Streaming:

https://cdn.example.com/secure/TOKEN/1777545540/coffee_run/master.m3u8
https://cdn.example.com/secure/TOKEN/1777545540/coffee_run/rendition-1080.m3u8
https://cdn.example.com/secure/TOKEN/1777545540/coffee_run/segment-001.ts

Example of token in path for Gcore Video Streaming:

https://demo-protected.gvideo.io/videos/2675_pG8TfmKx2LU2qs/rI1224fiE3USCa8qYnMuGQ/1861919999/master.m3u8

Where:

https://demo-protected.gvideo.io is the CDN URL
/videos/2675_pG8TfmKx2LU2qs/ is the video ID
rI1224fiE3USCa8qYnMuGQ is the token
1861919999 is the expiration time in Unix timestamp format

Scripts for link generation

PHP

Script with IP-based access restriction — the file is accessible only from the allowlisted IP address until the link expires:

<?php
$secret = 'secret_key';
$ip = '1.2.3.4';
$path = '/live/133529_2/chunklist.m3u8';
$expires = time() + 10000;
$link = "$expires$path$ip $secret";
$md5 = md5($link, true);
$md5 = base64_encode($md5);
$md5 = strtr($md5, '+/', '-_');
$md5 = str_replace('=', '', $md5);
$url = "http://cdn.site.com{$path}?md5={$md5}&expires={$expires}";
echo $url;
echo "\n";

Script without IP restriction — the file is accessible from any IP address until the link expires:

<?php
$secret = 'secret_key';
$path = '/live/133529_2/chunklist.m3u8';
$expires = time() + 10000;
$link = "$expires$path $secret";
$md5 = md5($link, true);
$md5 = base64_encode($md5);
$md5 = strtr($md5, '+/', '-_');
$md5 = str_replace('=', '', $md5);
$url = "http://cdn.site.com{$path}?md5={$md5}&expires={$expires}";
echo $url;
echo "\n";

In these scripts:

$secret is the secret key
$path is the path to the file
$ip is the IP address allowed to access the content
$expires is the link expiration time as a Unix timestamp
$url is the address of the file

Python

Script with IP-based access restriction:

import base64
from hashlib import md5
from time import time

secret = 'secret_key'
path = "/images/1.jpg"
ip = '1.2.3.4'
ttl = 100000
expires = int(time()) + ttl
token_hash = md5(f"{expires}{path}{ip} {secret}".encode()).digest()
token = base64.b64encode(token_hash).decode().replace("\n", "").replace("+", "-").replace("/", "_").replace("=", "")
secured_url = f"http://cdn.site.com{path}?md5={token}&expires={expires}"
print(secured_url)

Script without IP restriction:

import base64
from hashlib import md5
from time import time

secret = 'secret_key'
path = "/images/1.jpg"
ttl = 100000
expires = int(time()) + ttl
token_hash = md5(f"{expires}{path} {secret}".encode()).digest()
token = base64.b64encode(token_hash).decode().replace("\n", "").replace("+", "-").replace("/", "_").replace("=", "")
secured_url = f"http://cdn.site.com{path}?md5={token}&expires={expires}"
print(secured_url)

In these scripts:

secret is the secret key
path is the path to the file
ip is the IP address allowed to access the content
expires is the link expiration time as a Unix timestamp
secured_url is the link to the file

OpenSSL

Script that limits the link lifespan and restricts access to an allowlisted IP:

echo -n '2147483647/images/1.jpg1.2.3.4 secret_key' | openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
# Pattern: '{expires}{path}{ip} {secret_key}'

Script that only limits the link lifespan:

echo -n '2147483647/images/1.jpg secret_key' | openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
# Pattern: '{expires}{path} {secret_key}'

In these scripts:

2147483647/images/1.jpg is the path to the file prefixed with the expiration timestamp
1.2.3.4 is the IP address allowed to access the content
secret_key is the key entered in step 4 of the portal configuration

These scripts generate the secure token only. A separate script is needed to construct the full signed URL in the format {path}?md5={token}&expires={expires}.

IP binding and mobile networks

When a secure token is bound to the client’s IP address, the CDN recomputes the hash using the IP it sees on the incoming request. This becomes a problem on some mobile networks. In certain countries, mobile ISPs change a subscriber’s public IP address very aggressively — sometimes within minutes — because they route many subscribers through carrier-grade NAT (CGNAT) and rotate addresses across a pool. A token signed for one IP fails as soon as the carrier moves the user to another. The effect is most visible with Query String Forwarding for video. The player requests the manifest, gets a token, and the token is forwarded to related sub-segments. If the mobile ISP switches the client IP between requests, the next segment returns 403 while earlier segments returned 200. Receiving 200 and 403 responses almost simultaneously for the same user on a mobile network is a strong indicator of mobile IP rotation rather than an expired or malformed token. For Enterprise customers, Gcore can change the default token behavior from binding to a dedicated IP to binding to a wider subnet mask — /24 or /16 for very aggressive mobile operators. A wider mask still ties the URL to the ISP block — external sharing and hotlinking remain blocked — while tolerating IP rotation within that block. To enable it, contact Gcore support or an account manager.

Account settings

Developer Tools

CDN

FastEdge

Edge Cloud

AI

Gclaw

Managed DNS

Public DNS

Hosting

Colocation

Object Storage

Video Streaming

DDoS protection

Edge Proxy

WAAP

Configure secure token in the Customer Portal

Set up token generation on the origin server

Secure token URL matching

Token for exact file

Protect HLS and MPEG-DASH content

Token in a path

Scripts for link generation

PHP

Python

OpenSSL

IP binding and mobile networks

​Configure secure token in the Customer Portal

​Set up token generation on the origin server

​Secure token URL matching

​Token for exact file

​Protect HLS and MPEG-DASH content

​Token in a path

​Scripts for link generation

​PHP

​Python

​OpenSSL

​IP binding and mobile networks

Configure secure token in the Customer Portal

Set up token generation on the origin server

Secure token URL matching

Token for exact file

Protect HLS and MPEG-DASH content

Token in a path

Scripts for link generation

PHP

Python

OpenSSL

IP binding and mobile networks