Token Authentication

Detailed token generation and 403 troubleshooting.

Token Authentication

When enabled, requests must include a valid token and expiration timestamp. Invalid or expired signatures are rejected with 403.

  • Primary token parameter: acdn_token.
  • Required expiration parameter: expires (Unix timestamp).
  • Optional scope parameter: token_path.
  • Optional IP binding uses the client source IP in the signature payload.
  • Both query-token and path-token URL styles are supported.

Token Generation Flow

ACDN uses a signed URL flow with ACDN-specific parameter naming.

  1. Normalize request path and choose signed path: token_path if provided, otherwise request path.
  2. Collect request parameters and remove auth fields: acdn_token and expires.
  3. Sort parameter keys in lexical order and serialize as key=value pairs joined by ampersand.
  4. Build hashable payload: token_key + signed_path + expires.
  5. If token_ip is enabled, append client IP address to payload.
  6. Append serialized parameters and compute SHA-256 hash (base64url output, no padding).
  7. Send token in acdn_token and expiry in expires.

Implementation summary:

Signing flow
hashable = token_key + signed_path + expires
if token_ip_enabled:
  hashable += client_ip
hashable += canonical_query_without(acdn_token, expires)
token = base64url(sha256(hashable))

Token Parameters and Scope

acdn_token

Required

Primary token field.

expires

Required

Unix timestamp in seconds. Requests are rejected after expiration.

token_path

Optional

Scope prefix for token validity. Request path must match this scope.

token_ip

Optional (zone setting)

When enabled on zone, client IP is part of signature payload.

Signing URL Formats

Query token format:

URL
https://cdn.example.uz/video/intro.mp4?acdn_token=TOKEN_VALUE&expires=1767225600

Path token format:

URL
https://cdn.example.uz/acdn_token=TOKEN_VALUE&expires=1767225600/video/intro.mp4

Scoped token with token_path:

URL
https://cdn.example.uz/video/intro.mp4?quality=hd&acdn_token=TOKEN_VALUE&expires=1767225600&token_path=/video

HLS manifest protection with token_path:

Protect the path before index.m3u8 (exclude manifest filename). Use path-style token so the same token segment is reused for relative chunks.

Signed manifest URL (path-style token):

Manifest URL
https://cdn.example.uz/acdn_token=TOKEN_VALUE&expires=1767225600&token_path=%2Flive%2Fch-1/live/ch-1/index.m3u8

Next relative chunk request resolved by player:

Segment URL
https://cdn.example.uz/acdn_token=TOKEN_VALUE&expires=1767225600&token_path=%2Flive%2Fch-1/live/ch-1/seg-00001.ts

PHP example aligned with ACDN signer:

PHP
$params = ['quality' => 'hd', 'token_path' => '/video'];
$expires = time() + 3600;
ksort($params, SORT_STRING);

$hashParts = [];
foreach ($params as $key => $value) {
    $hashParts[] = $key . '=' . (string) $value;
}

$hashable = $tokenKey . '/video' . $expires . implode('&', $hashParts);
$token = rtrim(strtr(base64_encode(hash('sha256', $hashable, true)), '+/', '-_'), '=');

Common 403 Causes

  • Clock skew or stale expiration value.
  • Signed path does not match request path or token_path scope.
  • Query parameters changed after signing.
  • Request IP changed while zone requires token_ip binding.
  • Token generated with non-base64url encoding or with padding.

Token Test (Docs)

Generate ACDN-compatible query-style and path-style links directly in your browser.

Use relative URI like /live/ch-1/index.m3u8 or full URL.
Optional scope path. For HLS, set path before index.m3u8 (exclude manifest filename).
Secret key used for hash generation.
Unix time in seconds.
Required only when IP binding is enabled.
Query Param Style
Path Param Style