URL Suffixes

URL suffixes are special tokens appended to downloadUrl and thumbnailUrl that tell the CI HUB client how to handle authentication and caching when fetching the file. The client strips the suffix before making the actual HTTP request.

Reference

Suffix	Client behavior
$AUTH_SESSION_ID$	Appends the server session ID to the URL. Used by server-side adapters where downloads are proxied through the CI HUB backend
$FORCE_DOWNLOAD$	Forces the client to download the file (not display inline). Sets the `Content-Disposition: attachment` behavior
$REQUEST_HEADERS$	Reads custom headers from a `headers` query parameter on the URL (JSON-encoded). Supports `type=merge` (default), `type=replace`, or `type=overwrite` to control how custom headers combine with existing headers
$NO_AUTH$	Signals that the URL is publicly accessible — no auth headers are sent. The client downloads directly without proxying
$AUTH_PAYLOAD$	Replaces the suffix with the URL-encoded access token as a query parameter value
$AUTH_PAYLOAD_BEARER$	Replaces the suffix with URL-encoded `Bearer {token}` as a query parameter value
$AUTH_HEADER_PAYLOAD_BEARER$	Strips the suffix and adds an `Authorization: Bearer {token}` header
$AUTH_HEADER_PAYLOAD_APITOKEN$	Strips the suffix and adds an `Authorization: apiToken {token}` header
$NO_CACHE$	Strips the suffix and adds a `Cache-Control: no-cache` header

Common patterns

Public URLs

When your platform returns pre-signed or publicly accessible download URLs, append $NO_AUTH$ so CI HUB downloads directly:

const downloadUrl = `${asset.publicUrl}$NO_AUTH$`

Bearer token in header

When the download endpoint requires the same OAuth token your adapter uses, append $AUTH_HEADER_PAYLOAD_BEARER$ . The client adds the Authorization: Bearer header automatically:

const downloadUrl = `https://api.example.com/assets/${asset.id}/download$AUTH_HEADER_PAYLOAD_BEARER$`

Token as query parameter

Some APIs expect the token in the URL itself. Use $AUTH_PAYLOAD$ inside a query parameter:

const downloadUrl = `https://api.example.com/assets/${asset.id}/content?token=$AUTH_PAYLOAD$`

Custom headers via $REQUEST_HEADERS$

For APIs that need non-standard headers (e.g. API keys, custom auth schemes), encode headers as JSON in a headers query parameter:

const customHeaders = encodeURIComponent(JSON.stringify({
  'X-Api-Key': apiKey,
  'X-Custom-Auth': customToken,
}))
const downloadUrl = `https://api.example.com/assets/${asset.id}/download?headers=${customHeaders}$REQUEST_HEADERS$`

The type parameter controls header merging:

merge (default) — merges custom headers with existing ones, custom headers win on conflict
replace — uses only the custom headers, discards existing ones
overwrite — existing headers win on conflict

Force download

Append $FORCE_DOWNLOAD$ when the URL would otherwise render inline (e.g., images, PDFs) and you want to ensure a file download:

const downloadUrl = `${asset.viewUrl}$FORCE_DOWNLOAD$`

Disable caching

Append $NO_CACHE$ for URLs that return different content each time (e.g., latest version redirects):

const thumbnailUrl = `${asset.previewUrl}$NO_CACHE$`

How the client processes suffixes

The client runs parseUrl() which processes suffixes in this order:

$AUTH_SESSION_ID$ — stripped (SDK adapters don't use server sessions)
$FORCE_DOWNLOAD$ — stripped, flags the download as forced
$HEADER_VALUE_STATIC_ENCODED_* — static header extraction (internal)
$NO_CACHE$ — stripped, adds Cache-Control: no-cache
Auth suffixes (mutually exclusive — only the first match applies):
- $REQUEST_HEADERS$
- $NO_AUTH$
- $AUTH_PAYLOAD$
- $AUTH_PAYLOAD_BEARER$
- $AUTH_HEADER_PAYLOAD_BEARER$
- $AUTH_HEADER_PAYLOAD_APITOKEN$

Auth suffixes are mutually exclusive. Use only one per URL. Non-auth suffixes ( $FORCE_DOWNLOAD$ , $NO_CACHE$ ) can be combined with any auth suffix.

On this page