Skip to main content
Advanced token authentication uses HMAC-SHA256 signing and supports directory-level tokens for video streaming, country-based restrictions, IP locking, speed limits, and query parameter control.

​
URL structure

Signed URLs use either a query string or path-based format: 
https://myzone.b-cdn.net/videos/playlist.m3u8?token=HS256-abc123&expires=1598024587&token_path=%2Fvideos%2F

https://myzone.b-cdn.net/bcdn_token=HS256-abc123&expires=1598024587&token_path=%2Fvideos%2F/videos/playlist.m3u8

​
Parameters

ParameterRequiredDescription
tokenYesHashed signature
expiresYesUNIX timestamp in seconds when the URL becomes invalid
token_pathNoURL-encoded path prefix for directory-level access
token_countriesNoComma-separated allowed country codes (ISO 3166-1)
token_countries_blockedNoComma-separated blocked country codes (ISO 3166-1)
token_ignore_paramsNoWhen true, query parameters are excluded from token validation
limitNoDownload speed limit in kB/s

​
Directory tokens

By default, tokens are valid only for the exact URL path. Directory tokens allow access to any file within a path prefix, essential for video streaming where players request multiple segment files. Signing with token_path=/videos/stream1/ allows access to all files in that directory: 
/videos/stream1/playlist.m3u8
/videos/stream1/segment1.ts
/videos/stream1/segment2.ts

​
IP locking

IP locking binds a token to a specific client IP address. Any request from a different IP will be rejected, even if the token is otherwise valid. This is useful for preventing token sharing or URL redistribution. To use IP locking, pass the client’s IP address (IPv4 or IPv6) as the userIp parameter when signing the URL. The IP is included in the HMAC signature but is not appended to the URL itself.
IP locking requires the Token IP Validation setting to be enabled on your Pull Zone. Enabling this without including the IP in your tokens will cause all requests to fail.
IP locking can cause issues for users behind proxies, VPNs, or with frequently changing IP addresses (e.g. mobile networks).

​
Expiration

By default, the token expiry is calculated as a relative offset from the current time using expirationTime (in seconds). If you need the URL to expire at a specific point in time, use expiresAt to set an absolute UTC timestamp instead. When expiresAt is set, expirationTime is ignored.

​
Ignore query parameters

By default, all query string parameters present on the URL are included in the token signature. If a parameter is added, removed, or changed after signing, the token will fail validation. Set ignoreParams to true when you need to append arbitrary query parameters to signed URLs after generation, for example, analytics tags, cache-busting parameters, or player configuration. When enabled, the token_ignore_params=true parameter is included in the signature instead of the actual query parameters.

​
Speed limits

The limit parameter restricts the maximum download speed for the request in kB/s. Pass the desired speed as the speedLimit parameter when signing. A value of 0 means no limit. 
https://myzone.b-cdn.net/video.mp4?token=HS256-abc123&limit=500&expires=1598024587

​
Country restrictions

Use token_countries to allow access only from specific countries, or token_countries_blocked to allow all except specific countries (only one should be necessary per token). Country codes follow the ISO 3166-1 alpha-2 format (e.g. US, GB, DE).

​
Generate the token

token = "HS256-" + Base64URL(HMAC-SHA256(security_key, signature_path + expires + signing_data + user_ip))
Where:
  • security_key is used as the HMAC key (not included in the message)
  • signature_path is the URL path, or the token_path override if set
  • signing_data is the alphabetically-sorted parameters joined as key=value pairs separated by &, excluding token and expires
  • user_ip is the optional IP address (empty string if not set)
After Base64 encoding, replace + with -, / with _, and remove = padding characters.

​
Code examples

Tested implementations are available for C#, Python, Node.js, PHP, Java, Go, and Rust in the BunnyCDN.TokenAuthentication repository. 
var url = TokenSigner.SignUrl(t =>
{
    t.Url = "https://myzone.b-cdn.net/videos/stream1/playlist.m3u8";
    t.SecurityKey = "your-security-key";
    t.ExpiresAt = DateTimeOffset.UtcNow.AddHours(1);
    t.IsDirectory = true;
    t.TokenPath = "/videos/stream1/";
    t.CountriesAllowed = new List<string> { "GB" };
});

​
Query string vs path-based tokens

The isDirectory parameter controls how the token is embedded in the URL:
  • false (query string) - the token and parameters are appended as query string parameters. Suitable for direct file downloads and simple URL signing.
  • true (path-based) - the token is embedded in the URL path as /bcdn_token=.... This is required for HLS/DASH video delivery, where the player resolves relative segment URLs against the manifest path. Placing the token in the path ensures segment requests automatically inherit authentication without modifying the player.