Link Tokens

Streaming links in the API are represented as link tokens — encrypted, opaque strings that resolve to provider-specific URLs when accessed through our redirect service.

Why tokens?

Raw streaming URLs (e.g., netflix.com/title/12345) are never exposed in the API or snapshots. Instead, each link is encrypted into a token like 3xK9mP.... This design:

• Protects providers — URLs can’t be scraped or hotlinked
• Enables affiliate tracking — the redirect service injects attribution parameters
• Generates deep links — the redirect returns device-specific URLs (web, Fire TV, Android TV, tvOS, Roku, webOS)
• Supports key rotation — tokens can be re-encrypted without changing the data format

How it works

1. Fetch streaming links for a title via the API:

   curl -H "Authorization: Bearer YOUR_KEY" \
     "https://api.popcorntime.app/v1/media/jR9Lk5mP/links?country=US"

   Response:

   [
     {
       "provider_id": "netflix",
       "link_token": "3xK9mPv2bQ7nRtYs...",
       "price_types": ["flatrate"],
       "formats": ["HD", "UHD"]
     }
   ]

2. Redirect the user through the redirect service:

   https://popcorntime.app/go/{link_token}

   The service decrypts the token, generates the platform-appropriate deep link, injects affiliate parameters, and returns a 302 redirect to the provider.

3. The user lands on the provider’s page (Netflix, Disney+, etc.) with the correct title pre-selected.

Redirect URL format

https://popcorntime.app/go/{link_token}

Query parameters

Parameter	Description
platform	Target platform for the deep link

Available platforms:

Platform	Value	Description
Web browser	web	Standard HTTPS URL
iOS	ios	Universal link / app URI scheme
Android	android	Android intent / app link
Android TV	android_tv	Android TV deep link
Fire TV	fire_tv	Amazon Fire TV deep link
Roku	roku	Roku channel deep link
webOS (LG)	webos	LG Smart TV deep link

Example:

https://popcorntime.app/go/3xK9mPv2bQ7nRtYs?platform=fire_tv

How to know which platforms are available

Each link in the API response includes a platforms array listing the supported platforms for that specific provider link:

{
  "provider_id": "netflix",
  "link_token": "3xK9mPv2bQ7nRtYs...",
  "platforms": ["web", "ios", "android", "android_tv", "fire_tv"],
  "price_types": ["flatrate"],
  "formats": ["HD", "UHD"]
}

Only pass a platform value that appears in the link’s platforms array. If you omit it, the redirect service defaults to web.

Tip

Each link has one token that works for all its platforms. You don’t need different tokens per platform — just pass the platform query parameter and the redirect service generates the right deep link.

Token format

Tokens are AES-256-SIV encrypted and bs58 encoded:

bs58([ key_version: u8 ] ++ aes_siv_encrypt(key, url_bytes))

Caution

Tokens cannot be decrypted without the server-side key. This is intentional — raw provider URLs are never distributed in the API, snapshots, or open-source releases.

The 1-byte version prefix supports key rotation. Old tokens remain valid as long as the previous key is retained server-side.

Integration example

HTML link

<a href="https://popcorntime.app/go/3xK9mPv2bQ7nRtYs">
  Watch on Netflix
</a>

JavaScript (open in new tab)

function watchOn(linkToken) {
  window.open(`https://popcorntime.app/go/${linkToken}`, '_blank');
}

Smart TV / Set-top box

Pass the platform parameter to get the correct deep link for the device:

const platform = detectPlatform(); // "fire_tv", "android_tv", "webos", etc.
const url = `https://popcorntime.app/go/${token}?platform=${platform}`;
// The redirect service returns a platform-specific URI scheme

In Parquet snapshots

The links.parquet file contains a link_token column. These tokens work the same way — pass them through the redirect service:

-- DuckDB: get all Netflix links for a title
SELECT link_token, provider_id, price_types
FROM 'US_links.parquet'
WHERE media_id = 12345 AND provider_id = 'netflix';

Then redirect: https://popcorntime.app/go/{link_token}