Use this procedure to put Mux video behind a paywall: build paid or members-only playback into an application, protect videos that are currently public, or audit an existing gated integration. Your application decides who has paid. Mux enforces that decision through signed playback: each video uses a signed playback policy, and your server issues a short-lived JSON Web Token (JWT) only to viewers who are entitled to watch. DRM is an optional additional layer for premium content.

Follow the user's requirements and existing project instructions. Reuse the tools, credentials, authentication, and billing integration already available. If a Mux MCP server is already connected, use it for Mux operations. If the environment has no Mux credentials yet and you can run shell commands, sign in with the Mux CLI: run npx @mux/cli login, or mux login if it is installed. It opens a browser where the user approves access and chooses the Mux environment, so nobody creates or pastes an access token. Agent shells and ! commands are not interactive terminals, where a plain login exits with an error. Run npx @mux/cli login --json in the background instead: it writes the authorization URL as a JSON line on stderr and waits up to five minutes for the user to approve. Give the user that URL and wait for the command to finish. Without a shell, fetch https://www.mux.com/prompts/onboarding.md and complete it first; it connects the Mux MCP server. The examples and defaults below are starting choices; adapt them to the request.

Canonical instructions: /docs/prompts/video-paywall.md. Browse other use cases in the prompt library at /docs/prompts.md. For repeated use in an agent that supports skills, use /skills/mux-video-paywall/SKILL.md as the entry point.

Track your progress with this checklist

Copy this checklist into your task list or plan before starting, and keep it updated as you work. Mark each item done, skipped with the reason, or blocked with what is needed. Include the final state of the checklist in your report to the user.

1. Identify the mode: build an application, protect existing videos, or audit an existing integration.
2. Check the environment for Mux credentials and tools. If there are none, sign in with the Mux CLI as described above. If you cannot check, say so and offer the CLI sign-in rather than asking the user for an access token.
3. Resolve every question in the table under Start with the request: answered by the user, answered from the project, or not applicable with the reason.
4. Choose the protection level and state why, including whether DRM or playback restrictions are needed.
5. Complete each numbered step that applies, or record why it was skipped.
6. Run every check under Verify the result that applies, against a real video where credentials allow.
7. Report which checks ran against real Mux and billing state, and which still need credentials, a test purchase, or target devices.

Start with the request

First determine whether the user wants to build an application with gated playback, protect existing videos that are already in Mux, or audit an existing integration. A codebase is needed for the first mode. The second can run against the Mux API alone, though viewers still need a server that issues tokens before they can watch.

Inspect the available project, its authentication and billing code, and configured tools before asking questions. Use what the user has already told you, and ask only for missing choices that change the work:

Treat payment processing, account management, and entitlement storage as the application's responsibility. Use the project's existing providers. When none exists, ask the user which to use rather than choosing one for them.

Choose an execution method

If a needed operation is unavailable, explain the handoff rather than inventing a tool. Never place a signing key's private key in client code, a repository, or a chat transcript.

Choose a protection level

Signed playback is the baseline for every paywall. A valid token works for anyone who holds it until it expires, so expiration time, playback restrictions, and DRM determine how far a shared token can travel. Start with signed playback and add layers when the content's value calls for them.

1. Create a signing key and store it on the server

Signing keys are separate from API access tokens. With the Mux CLI signed in, create one with:

npx @mux/cli signing-keys create

The CLI saves the key ID and private key to its own configuration for the signed-in environment and does not print the private key. npx @mux/cli sign YOUR_SIGNED_PLAYBACK_ID then signs test URLs with it, which is enough to verify Mux's enforcement. The application's server needs the same two values as MUX_SIGNING_KEY and MUX_PRIVATE_KEY: they are stored as signingKeyId and signingPrivateKey for the environment in ~/.config/mux/config.json. Ask the user to copy them into the server's secret store, such as .env.local, instead of reading or printing the private key yourself.

Without the CLI, create a key from the Signing Keys settings in the dashboard, or with the API:

curl -X POST https://api.mux.com/system/v1/signing-keys \
  --user "$MUX_TOKEN_ID:$MUX_TOKEN_SECRET"

The response contains the key id and a base64-encoded private_key. Mux keeps only the public key, and later requests for the signing key do not return the private key, so save it to the server's secret store as soon as it is returned. The Mux TypeScript SDK (@mux/ts) reads these values from MUX_SIGNING_KEY (the key ID) and MUX_PRIVATE_KEY (the base64-encoded private key). Signing keys belong to one Mux environment; use a key from the same environment as the videos.

Creating a signing key through the API needs an access token with System write permission, and creating assets needs Mux Video write. A CLI sign-in covers both. The server that issues playback tokens needs neither: the SDK signs tokens locally, so new Mux() works there with only MUX_SIGNING_KEY and MUX_PRIVATE_KEY set. Keep the access token out of that server unless it also calls the API.

One active key is usually enough. To rotate, create a new key, switch the server to it, and delete the old key only after tokens signed with it have expired.

2. Give each video a signed playback ID

A video's playback policy determines whether a token is required. An asset created without any playback policy cannot be played at all until a playback ID is added.

New on-demand videos. Set the policy when creating the asset. For direct uploads, set the same field inside new_asset_settings. With the CLI:

npx @mux/cli assets create --url https://example.com/your-video.mp4 --playback-policy signed --video-quality basic --wait --json

Or with the API:

curl https://api.mux.com/video/v1/assets \
  --user "$MUX_TOKEN_ID:$MUX_TOKEN_SECRET" \
  --header "Content-Type: application/json" \
  --data '{
    "inputs": [{ "url": "https://example.com/your-video.mp4" }],
    "playback_policies": ["signed"],
    "video_quality": "basic"
  }'

Use basic video quality as a starting point; choose a different quality level if the content needs it. Wait for video.asset.ready before offering playback.

Existing videos with public playback IDs. Add a signed playback ID, move the application to it, then remove the public one:

curl https://api.mux.com/video/v1/assets/YOUR_ASSET_ID/playback-ids \
  --user "$MUX_TOKEN_ID:$MUX_TOKEN_SECRET" \
  --header "Content-Type: application/json" \
  --data '{ "policy": "signed" }'

An asset can hold several playback IDs at once, so both work during the transition. The video remains publicly playable until the public playback ID is deleted with DELETE /video/v1/assets/{ASSET_ID}/playback-ids/{PLAYBACK_ID}. Deleting it breaks every existing embed and link that uses that ID, and a viewer who started watching beforehand may be able to continue for a limited time. Confirm with the user before deleting public playback IDs, and migrate in batches with a saved record of each asset's old and new IDs so the work can be resumed.

Live streams. Create the live stream with a signed playback policy, and set the same policy in new_asset_settings so recordings of the stream are gated as well. See start live streaming.

Save each video's playback ID and its policy in the application's database. Appending a token to a URL for a public playback ID makes the request fail, so an application that mixes free and paid videos needs to know which IDs to sign for.

3. Add playback restrictions if you need them

A playback restriction limits which sites or clients can play a signed video. Restrictions exist at the environment level and apply only when a token references one through the playback_restriction_id claim.

curl https://api.mux.com/video/v1/playback-restrictions \
  --user "$MUX_TOKEN_ID:$MUX_TOKEN_SECRET" \
  --header "Content-Type: application/json" \
  --data '{
    "referrer": {
      "allowed_domains": ["example.com", "*.example.com"],
      "allow_no_referrer": false
    },
    "user_agent": {
      "allow_no_user_agent": false,
      "allow_high_risk_user_agent": false
    }
  }'

Save the returned id. Account for these documented behaviors before enabling a restriction:

• A wildcard covers one subdomain level: *.example.com does not match example.com or a.b.example.com. List each pattern you need.
• Native iOS and Android apps do not send a Referer header. Create a second restriction with allow_no_referrer: true for native clients, and reference the appropriate restriction ID in tokens for web versus native viewers.
• Chromecast needs www.gstatic.com in the allowed domains. AirPlay to third-party devices needs mediaservices.cdn-apple.com, and first-party Apple devices never send a referrer, so they require allow_no_referrer: true.
• Include local development and preview domains in a separate restriction for non-production use, so that the production allow list stays narrow.

4. Issue tokens from an entitlement-checked endpoint

Build a server endpoint that authenticates the viewer, checks their entitlement to the requested video, and only then signs tokens. This check is the paywall. Do it on every token request, against current billing state, and look up the playback ID on the server from your own video record rather than signing whatever ID the client sends.

Each protected resource needs its own token, distinguished by the aud claim:

Every token carries sub (the playback ID), aud, exp (expiration in UNIX epoch seconds), and kid (the signing key ID), and is signed with the RS256 algorithm. With the Mux TypeScript SDK, one call can return the playback, thumbnail, and storyboard tokens:

import Mux from '@mux/ts';

// Reads MUX_SIGNING_KEY and MUX_PRIVATE_KEY from the environment
const mux = new Mux();

const tokens = await mux.jwt.signPlaybackId(playbackId, {
  type: ['video', 'thumbnail', 'storyboard'],
  expiration: '6h',
  params: { playback_restriction_id: PLAYBACK_RESTRICTION_ID },
});
// { 'playback-token': '...', 'thumbnail-token': '...', 'storyboard-token': '...' }

Omit params when no playback restriction is used. For other languages, see the examples in signing JWTs; any JWT library that supports RS256 works.

Choose the expiration deliberately. When a token expires the URL stops working, even if playback has already started. Set exp to at least the current time plus the video's duration, or the expected length of a live stream. The 6h above is an illustrative value. Shorter lifetimes limit how long a shared token stays useful. Fetch new tokens when a viewer returns to a page after a long absence, and consider tying expiration to the end of a rental or billing period when access should end at a known time.

Options belong in the claims. For a signed playback ID, thumbnail options such as time and width, and playback modifiers such as default_subtitles_lang, must be set as claims in the token. The final URL should contain only the token query parameter. Parameters added next to the token are not covered by the signature, so do not rely on Mux either applying or rejecting them.

Trace shared tokens without personal data. A custom claim can carry a session reference that lets you trace a leaked URL to the account that requested it. Never put names, email addresses, or other personally identifiable information in a token.

{
  "sub": "YOUR_PLAYBACK_ID",
  "aud": "v",
  "exp": 1790000000,
  "kid": "YOUR_SIGNING_KEY_ID",
  "custom": { "session_id": "xxxx-123" }
}

Keep entitlements current

Access ends when the endpoint stops issuing tokens, so the entitlement record has to follow billing changes: cancellations, failed payments, refunds, and expired rentals. Update it from the billing provider's verified events, using the project's existing integration. A token that was already issued remains valid until its exp; choose lifetimes with that in mind. For an emergency removal, deleting the playback ID cuts off access for everyone, and a new signed playback ID restores it for entitled viewers.

5. Play the video with tokens

Use Video.js 10 with its Mux video component. If the project already plays video with another player, keep it and give it the signed URLs instead.

Each token goes in the source group for the URL it signs. The playback token goes at source.playback.token, the thumbnail token at source.poster.token, and the storyboard token at source.storyboard.token. Video.js checks the audience of the poster and storyboard tokens and skips the poster or the timeline previews when one is missing or has the wrong audience. Playback tokens pass through to Mux, so a misplaced one shows up as a rejected stream request. In React:

npm install @videojs/react @videojs/mux-video @videojs/mux-data

'use client';

import '@videojs/react/video/skin.css';
import { VideoPlayer, VideoSkin } from '@videojs/react/video';
import { MuxData } from '@videojs/react/extensions/mux-data';
import { MuxVideo } from '@videojs/react/media/mux-video';

// tokens is the response from the entitlement-checked token endpoint
export function PaidVideo({ playbackId, tokens }) {
  return (
    <VideoPlayer>
      <VideoSkin style={{ aspectRatio: '16 / 9' }}>
        <MuxVideo
          source={{
            playbackId,
            playback: { token: tokens['playback-token'] },
            poster: { token: tokens['thumbnail-token'] },
            storyboard: { token: tokens['storyboard-token'] },
          }}
          playsInline
          crossOrigin="anonymous"
        />
        <MuxData />
      </VideoSkin>
    </VideoPlayer>
  );
}

Without React, install @videojs/html instead, import @videojs/html/video/player, @videojs/html/video/skin, and @videojs/html/media/mux-video, and set the same object on the element's source property:

document.querySelector('mux-video').source = {
  playbackId: 'YOUR_SIGNED_PLAYBACK_ID',
  playback: { token: 'YOUR_PLAYBACK_TOKEN' },
  poster: { token: 'YOUR_THUMBNAIL_TOKEN' },
  storyboard: { token: 'YOUR_STORYBOARD_TOKEN' },
};

Follow the Video.js installation guides for the project's framework, and remove any Mux Player or Media Chrome imports from pages that load Video.js, since they register custom elements with the same names. MuxData reports playback to Mux Data without an environment key, because Mux attributes views to the environment that owns the playback ID. For other players, append the playback token to the stream URL:

https://stream.mux.com/YOUR_SIGNED_PLAYBACK_ID.m3u8?token=YOUR_PLAYBACK_TOKEN

Render the player only after the server has confirmed entitlement. Show non-paying visitors the purchase or sign-in prompt instead, optionally with a signed poster image. Hiding a player with CSS or client-side state is not protection; the absence of a valid token is.

The common token problems are a playback ID that does not match the token's sub, an expired token, and a malformed token. Video.js does not refresh tokens or report expired ones yet, so the application has to request fresh tokens before exp, retry after a playback error, and show the paywall when the endpoint refuses. Assigning a new source reloads the stream, so save the current time before swapping tokens and seek back to it once the new source has loaded metadata. Avoid swapping tokens on a stream that is playing without errors.

If the application offers downloadable MP4 files for a signed playback ID, those requests need signed URLs too. Generate them on demand behind the same entitlement check rather than storing them as permanent links.

Offer a free preview

A preview can come from the same signed video, without a second asset. Issue anonymous visitors a playback token whose claims include asset_start_time and asset_end_time, as described in signed instant clips. Because the range is part of the signed claims, the viewer cannot widen it. Add the same claims to the storyboard token, and use a thumbnail token for the poster. With the SDK, pass per-type claims as [type, params] pairs:

const clip = { asset_start_time: 0, asset_end_time: 30 };
const previewTokens = await mux.jwt.signPlaybackId(playbackId, {
  type: [['video', clip], ['storyboard', clip], 'thumbnail'],
  expiration: '15m',
});

The SDK's TypeScript types declare params values as strings, so TypeScript projects need a cast to pass these numbers. Instant clipping uses segment-level boundaries, so the preview may start or end slightly outside the requested times. Keep the range well short of the video's duration, and derive it from the asset's duration rather than a fixed number: a 30-second preview of a 25-second video is the whole video. Rate-limit the preview endpoint, since it serves unauthenticated visitors.

6. Add DRM for premium content

Signed playback controls who can start a stream. DRM adds video encryption, screen capture protection on supporting devices, and HDCP on Apple devices. Protection varies by device: desktop browsers typically rely on software decryption, where capture blocking is less dependable. Recommend DRM when the user's content or licensing terms require it, and state these prerequisites plainly:

• DRM is an add-on with a monthly access fee and a per-license charge; see DRM pricing. One license request typically corresponds to one view.
• Access is requested from Settings → Digital Rights Management in the dashboard, after which the environment receives a DRM configuration ID.
• Playback on Apple devices requires the user's own FairPlay certificate from Apple. Approval can take several days. Widevine and PlayReady are managed by Mux.
• DRM is supported on the plus and premium video quality levels.

Create DRM-protected assets with advanced_playback_policies. This field cannot be combined with playback_policies in the same request; include multiple entries in the array when more than one policy is needed.

{
  "inputs": [{ "url": "https://example.com/your-video.mp4" }],
  "advanced_playback_policies": [
    { "policy": "drm", "drm_configuration_id": "YOUR_DRM_CONFIGURATION_ID" }
  ],
  "video_quality": "plus"
}

A DRM playback ID can also be added to an existing asset through the playback IDs endpoint, for assets created after DRM was enabled in the environment. Playback needs both a playback token and a DRM license token, issued by the same entitlement-checked endpoint:

const playbackToken = await mux.jwt.signPlaybackId(playbackId, { expiration: '6h' });
const drmLicenseToken = await mux.jwt.signDrmLicense(playbackId, { expiration: '6h' });

In Video.js, put the license token at source.drm.token, next to source.playback.token. Video.js derives the FairPlay, Widevine, and PlayReady license servers and the FairPlay certificate from it; verify playback with the protected assets on every target browser. In native apps, Mux Player for iOS and Android supports DRM from version 1.1.0. For other players, build the license URLs described in the DRM guide. If DRM onboarding is still pending, ship signed playback first and add the DRM playback IDs afterward.

Visible watermarks are encoded into the video and are the same for every viewer. Per-viewer overlays drawn by the player are easier to bypass, and forensic watermarking is not currently available.

Audit an existing paywall

Use this section when the user already gates video and wants to know whether it holds. Work read-only until the user approves changes, and report findings with the asset or file they refer to.

1. List the gated videos from the application's records and retrieve each asset's playback IDs. Flag any gated asset that still has a public playback ID, and any gated live stream whose new_asset_settings would publish recordings publicly.
2. Read the token endpoint. Confirm that it authenticates the viewer, checks entitlement for the specific video against current billing state, and resolves the playback ID on the server. An endpoint that signs any ID a client supplies is a bypass.
3. Search the client bundle, repository history, environment files, and logs for the signing key's private key. If it has been exposed, rotate the key as described in step 1.
4. Review token lifetimes against video durations and the payment model, and check that billing events such as cancellations and refunds update the entitlement record.
5. Check playback restrictions against the clients in use, then run the checks under Verify the result.

Verify the result

Before calling the paywall complete, check that:

• Requesting https://stream.mux.com/YOUR_SIGNED_PLAYBACK_ID.m3u8 without a token is denied, and so are requests with an expired token and with a thumbnail token in place of the playback token. The SDK will not sign a token that is already expired; sign one with a short expiration and wait for it to pass, or sign the expired test token with a JWT library.
• The token endpoint refuses unauthenticated and non-entitled viewers, and cannot be made to sign a playback ID the viewer has not paid for.
• An entitled viewer can play the video, see the poster and timeline previews, and resume after returning to the page later.
• Cancelling or refunding a test purchase stops new tokens from being issued.
• No gated video still has a public playback ID, unless the user chose to keep one. List each asset's playback IDs to confirm.
• The signing key's private key exists only in the server's secret store: not in client bundles, the repository, logs, or API responses.
• Playback restrictions allow every intended client, including native apps, casting targets, and development domains, and deny an origin that is not listed.
• With DRM, playback works on each target platform, including an Apple device once the FairPlay certificate is in place.
• A preview token plays only its range, and the full video remains unavailable to the same visitor.

For an agent-built implementation, report which of these were tested against a real video and billing state, and which still need credentials, a test purchase, or target devices. Local checks alone do not establish that the paywall holds in production.

Understand the costs

The workflow incurs the usual encoding, storage, and delivery charges for each video. DRM adds a monthly access fee and per-license charges, and requires plus or premium video quality. Migrating an existing video adds a playback ID to the same asset rather than creating another one. Use the pricing overview and cost-estimation guide with your library size and expected viewing.