Restrict playback access

FastPix lets you control exactly where and how your videos can be played - whether you’re securing premium content, limiting access to trusted domains, or blocking certain browsers or apps. You can apply playback restrictions at three points in your workflow:

• When creating media using URL (Pull)
• When uploading media directly (Push)
• When creating a playback ID

For existing media, you can update restrictions at any time using:

• Update domain restrictions

  PATCH https://api.fastpix.io/v1/on-demand/{mediaId}/playback-ids/{playbackId}/domains

• Update user agent restrictions

  PATCH https://api.fastpix.io/v1/on-demand/{mediaId}/playback-ids/{playbackId}/user-agents

These controls give you fine-grained protection by limiting access by domain or by user agent.

1. Set restrictions when creating media

You can define restrictions directly into your media creation request (Create media from URL).

Example request:

{
  "inputs": [
    {
      "type": "video",
      "url": "https://static.fastpix.io/fp-sample-video.mp4"
    }
  ],
  "metadata": {
    "key1": "value1"
  },
  "accessPolicy": "public",
  "maxResolution": "1080p",
  "accessRestrictions": {
    "domains": {
      "defaultPolicy": "allow",
      "allow": ["example.com"],
      "deny": []
    },
    "userAgents": {
      "defaultPolicy": "allow",
      "allow": ["Mozilla/5.0"],
      "deny": []
    }
  }
}

2. Set restrictions when uploading media

If you’re pushing media to FastPix (Upload media from device), include restrictions inside pushMediaSettings.

Example request:

{
  "corsOrigin": "*",
  "pushMediaSettings": {
    "metadata": {
      "key1": "value1"
    },
    "accessPolicy": "public",
    "accessRestrictions": {
      "domains": {
        "defaultPolicy": "allow",
        "allow": ["example.com"],
        "deny": []
      },
      "userAgents": {
        "defaultPolicy": "allow",
        "allow": ["Mozilla/5.0"],
        "deny": []
      }
    },
    "maxResolution": "1080p"
  }
}

3. Set restrictions when creating a playback ID

When creating a playback ID, you can set their own restrictions, separate from the media’s default rules.

Example request:

{
  "accessPolicy": "public",
  "accessRestrictions": {
    "domains": {
      "defaultPolicy": "allow",
      "allow": [
        "players.akamai.com",
        "livepush.io"
      ],
      "deny": [
        "wowza.com",
        "5centscdn.net"
      ]
    },
    "userAgents": {
      "defaultPolicy": "deny",
      "allow": [
        "Mozilla/5.0",
        "Chrome/90.0"
      ],
      "deny": [
        "curl/7.68.0"
      ]
    }
  }
}

Domain restrictions

Domain restrictions control which websites can embed or stream your content. Here're the configuration options:

• Default policy – Allow or deny all domains by default.
• Allow list – Add up to 25 domains that are always allowed.
• Deny list – Add up to 25 domains that are always blocked.
• Wildcard support – Use patterns like *.example.com to include all subdomains.

User agent restrictions

User agent restrictions filter access by browser, app, or device. Here're the configuration options:

• Default Policy – Choose to allow or deny all user agents by default.
• Allow List – Add up to 25 exact user agent strings that are allowed.
• Deny List – Add up to 25 exact user agent strings that are blocked.

Note: User agent strings are case-sensitive.

Managing restrictions

Once playback restrictions are in place, you can review or adjust them without recreating your media or playback IDs. FastPix provides API endpoints to view current settings, update allowed/denied domains, or change user agent rules at any time.

1. View playback restrictions

Use this endpoint to retrieve a list of all playback IDs for a media item, along with the domain and user agent rules currently applied. This is useful for auditing access policies or confirming changes have taken effect.

GET https://api.fastpix.io/v1/on-demand/{mediaId}/playback-ids

2. Update domain restrictions

Change which websites can embed or stream your content. You can switch the default policy, add/remove domains from the allow list, or block specific domains - all without impacting the media file itself.

Use this endpoint:

PATCH https://api.fastpix.io/v1/on-demand/{mediaId}/playback-ids/{playbackId}/domains

Sample payload:

{
  "defaultPolicy": "allow",
  "allow": ["example.com", "*.example.com"],
  "deny": ["blocked.com"]
}

3. Update user agent Restrictions

Adjust which browsers, apps, or devices can play your content. Use this to block suspicious crawlers, allow only specific app versions, or apply stricter rules for certain streams.

Use this endpoint:

PATCH https://api.fastpix.io/v1/on-demand/{mediaId}/playback-ids/{playbackId}/user-agents

Sample payload:

{
  "defaultPolicy": "deny",
  "allow": ["Chrome/91.0", "Mozilla/5.0"],
  "deny": ["Bot/1.0", "Crawler/2.0"]
}

LIMITATIONS

Playback restriction settings have a few boundaries to ensure consistent enforcement across the FastPix platform:

• Maximum 25 entries in allow or deny lists (per type).
• Only valid domain names are accepted (wildcards supported like *.example.com).
• User agent strings are case-sensitive and must match exactly.

Webhook notifications

If you’ve connected webhooks to your FastPix workspace, you can automatically receive notifications whenever domain or user agent restrictions are updated. This helps teams stay in sync, trigger automation workflows, or log changes for security audits.

Events sent:

video.playbackId.user-agents.updated – Fired when user agent restrictions are added, removed, or changed.

video.playbackId.domains.updated – Fired when domain restrictions are modified.

Testing your restrictions

Before going live, verify that your rules behave as expected. Testing helps you catch configuration mistakes early and avoid blocking legitimate viewers.

• Try loading the playback URL from both allowed and blocked domains.
• Switch between different browsers, apps, or devices to confirm user agent rules work.
• Use developer tools like curl or Postman to send requests with custom User-Agent headers and simulate various clients.