Advanced Token Authentication

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

Parameter	Required	Description
`token`	Yes	Hashed signature
`expires`	Yes	UNIX timestamp in seconds when the URL becomes invalid
`token_path`	No	URL-encoded path prefix for directory-level access
`token_countries`	No	Comma-separated allowed country codes (ISO 3166-1)
`token_countries_blocked`	No	Comma-separated blocked country codes (ISO 3166-1)
`token_ignore_params`	No	When `true`, query parameters are excluded from token validation
`limit`	No	Download 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 address as the userIp parameter when signing the URL. The address is included in the HMAC signature but is not appended to the URL itself. Both IPv4 and IPv6 addresses are supported, and each family binds at a different prefix length:

Family	Binds at	Behavior
IPv4	`/32` or `/24`	Signing a full address (`203.0.113.42`) binds that exact address. Signing the network address of a `/24` (`203.0.113.0`) accepts any client within that `/24`.
IPv6	`/64`	Only the `/64` prefix is bound, so any address within it is accepted.

IPv6 always binds at /64 rather than the full address, because most clients change the rest of their address regularly for privacy. Binding the full address would stop validating as soon as it changed, often within hours, while a client’s /64 stays stable. For IPv4, you can widen the bind by signing the network address of a /24 (for example 203.0.113.0 instead of 203.0.113.42). Tokens signed that way validate for any client within that /24, which is useful for clients whose address shifts within a subnet.

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.

Address family matching

The signed address must be in the same family the request arrives over. A token signed with an IPv4 address cannot validate a request that arrives over IPv6, nor the reverse. Enabling Token IP Validation therefore pins the Pull Zone to a single family: the zone serves IPv4 only, unless its IP Family Policy is set to IPv6 Only, which is respected and makes the zone serve IPv6 only. Sign whichever family the zone serves.

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-" + flags + Base64URL(HMAC-SHA256(security_key, signature_path + expires + user_ip + signing_data))

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
user_ip is the optional IP address, omitted entirely when not set. IPv6 addresses are masked to their /64 prefix before signing
signing_data is the alphabetically-sorted parameters joined as key=value pairs separated by &, excluding token and expires
flags is 1- when an IP was signed, and empty otherwise, producing tokens of the form HS256-1-<hash>

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

from token import sign_url

url = sign_url(
    "https://myzone.b-cdn.net/videos/stream1/playlist.m3u8",
    "your-security-key",
    expiration_time=3600,
    is_directory=True,
    path_allowed="/videos/stream1/",
    countries_allowed="GB",
)

const { signUrl } = require('./token');

const url = signUrl(
    'https://myzone.b-cdn.net/videos/stream1/playlist.m3u8',
    'your-security-key',
    3600,                   // expirationTime
    '',                     // userIp
    true,                   // isDirectory
    '/videos/stream1/',     // pathAllowed
    'GB',                   // countriesAllowed
);

require_once 'url_signing.php';

$url = sign_bcdn_url(
    'https://myzone.b-cdn.net/videos/stream1/playlist.m3u8',
    'your-security-key',
    3600,                   // expiration_time
    '',                     // user_ip
    true,                   // is_directory
    '/videos/stream1/',     // path_allowed
    'GB',                   // countries_allowed
);

import BunnyCDN.TokenSigner;

String url = TokenSigner.signUrl(
    "https://myzone.b-cdn.net/videos/stream1/playlist.m3u8",
    "your-security-key",
    3600,                   // expirationTime
    "",                     // userIp
    true,                   // isDirectory
    "/videos/stream1/",     // pathAllowed
    "GB",                   // countriesAllowed
    ""                      // countriesBlocked
);

import bunnycdn "bunnycdn-token-authentication"

url, err := bunnycdn.SignUrl(
    "https://myzone.b-cdn.net/videos/stream1/playlist.m3u8",
    "your-security-key",
    3600,                   // expirationTime
    "",                     // userIp
    true,                   // isDirectory
    "/videos/stream1/",     // pathAllowed
    "GB",                   // countriesAllowed
    "",                     // countriesBlocked
    false,                  // ignoreParams
    nil,                    // expiresAt
    0,                      // speedLimit
)

use bunnycdn_token_authentication::sign_url;

let url = sign_url(
    "https://myzone.b-cdn.net/videos/stream1/playlist.m3u8",
    "your-security-key",
    3600,                   // expiration_time
    "",                     // user_ip
    true,                   // is_directory
    "/videos/stream1/",     // path_allowed
    "GB",                   // countries_allowed
    "",                     // countries_blocked
    false,                  // ignore_params
    None,                   // expires_at
    0,                      // speed_limit
)?;

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.

Documentation

Usage

Integrations

Reference

URL structure

Parameters

Directory tokens

IP locking

Address family matching

Expiration

Ignore query parameters

Speed limits

Country restrictions

Generate the token

Code examples

Query string vs path-based tokens

​URL structure

​Parameters

​Directory tokens

​IP locking

​Address family matching

​Expiration

​Ignore query parameters

​Speed limits

​Country restrictions

​Generate the token

​Code examples

​Query string vs path-based tokens

URL structure

Parameters

Directory tokens

IP locking

Address family matching

Expiration

Ignore query parameters

Speed limits

Country restrictions

Generate the token

Code examples

Query string vs path-based tokens