Playback restrictions prevent unauthorized access to your video content by limiting which domains can embed and play your videos.
Overview
All video playback is restricted by default:
- Only requests from allowed domains can play content
- URLs are signed with time-limited tokens
- Referrer headers are validated
Domain allowlist
Configuration
Add allowed domains via Admin Portal or API:
- Go to Settings → Playback Restrictions
- Add domains to the allowlist
- Save changes
curl -X PUT https://api.shortkit.dev/v1/config/playback-restrictions \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"allowedDomains": [
"yourcompany.com",
"*.yourcompany.com",
"staging.yourcompany.com"
]
}'
Domain formats
| Format | Example | Matches |
|---|
| Exact domain | yourcompany.com | Only yourcompany.com |
| Wildcard subdomain | *.yourcompany.com | Any subdomain (e.g., www., app., staging.) |
| Specific subdomain | app.yourcompany.com | Only app.yourcompany.com |
Examples
{
"allowedDomains": [
"yourcompany.com", // Main domain
"*.yourcompany.com", // All subdomains
"partner-site.com", // Specific partner
"192.168.1.100" // Local IP for development
]
}
Development environments
Automatic localhost access
In staging and development environments, these are automatically allowed:
localhost127.0.0.1*.localhost
Production environments require explicit domain configuration.
Environment-specific settings
Configure different restrictions per environment:
# Development - more permissive
curl -X PUT https://api.shortkit.dev/v1/config/playback-restrictions \
-H "Authorization: Bearer sk_test_your_key" \
-d '{ "allowedDomains": ["*"] }' # Allow all (dev only!)
# Production - strict
curl -X PUT https://api.shortkit.dev/v1/config/playback-restrictions \
-H "Authorization: Bearer sk_live_your_key" \
-d '{ "allowedDomains": ["yourcompany.com", "*.yourcompany.com"] }'
Never use wildcard (*) in production. This disables domain restrictions entirely.
Referrer handling
No-referrer requests
Some scenarios don’t send referrer headers:
- Direct URL access in browser address bar
- Some mobile app WebViews
- Privacy browser extensions
- HTTPS → HTTP transitions
Configure how to handle these:
curl -X PUT https://api.shortkit.dev/v1/config/playback-restrictions \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"allowedDomains": ["yourcompany.com"],
"allowNoReferrer": true
}'
| Setting | Default | Description |
|---|
allowNoReferrer | false | Allow requests with no referrer header |
If your mobile app has playback issues, try enabling allowNoReferrer. Some WebView implementations don’t send referrers.
User agent filtering
Block known scraping and bot user agents:
curl -X PUT https://api.shortkit.dev/v1/config/playback-restrictions \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"allowedDomains": ["yourcompany.com"],
"allowHighRiskUserAgents": false
}'
allowHighRiskUserAgents is false:
- Known scraper user agents are blocked
- Bot traffic is rejected
- Headless browser signatures are blocked
Signed URLs
How signing works
- Feed API returns content with signed streaming URLs
- Signature includes:
- Content ID
- Expiration timestamp
- Organization identifier
- CDN validates signature before serving
https://video.yourcompany.com/v1/streams/cnt_abc123/manifest.m3u8
?token=eyJhbGciOiJIUzI1NiIs...
&expires=1707048000
Token expiry
Configure how long tokens are valid:
curl -X PUT https://api.shortkit.dev/v1/config/cdn \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"urlExpiry": 21600
}'
| Setting | Default | Range | Description |
|---|
urlExpiry | 6 hours | 1-24 hours | Token validity in seconds |
- Shorter expiry: More secure, but may cause issues during long viewing sessions
- Longer expiry: Better user experience, but tokens remain valid longer if leaked
Automatic refresh
The SDK automatically handles token refresh:
- Monitors token expiry
- Refreshes before expiration
- Seamless to users
Error responses
Blocked requests
When a request is blocked, the CDN returns:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "PLAYBACK_RESTRICTED",
"message": "Domain not allowed",
"code": "DOMAIN_NOT_ALLOWED"
}
Error codes
| Code | Description |
|---|
DOMAIN_NOT_ALLOWED | Request domain not in allowlist |
TOKEN_EXPIRED | Signed URL token has expired |
TOKEN_INVALID | Token signature verification failed |
REFERRER_BLOCKED | Referrer header blocked |
USER_AGENT_BLOCKED | User agent blocked |
Monitoring
View blocked requests
In the Admin Portal:
- Go to Analytics → Playback Quality → Errors
- Filter by error type
- View blocked request details:
- Requesting domain
- User agent
- Timestamp
- Content requested
Alerts
Set up alerts for unusual block patterns:
- Go to Settings → Alerts
- Create rule for blocked request rate
- Get notified of potential issues or attacks
Testing restrictions
Verify configuration
Check current settings:
curl https://api.shortkit.dev/v1/config/playback-restrictions \
-H "Authorization: Bearer sk_live_your_secret_key"
Test from different domains
Use browser developer tools:
- Open your site in a browser
- Try to play a video
- Check Network tab for request/response
Test from unauthorized domain:
- Create a test HTML page on a different domain
- Embed your video player
- Verify playback is blocked
Troubleshooting
Legitimate traffic being blocked
Symptom: Users report videos not playing
Check:
- Verify domain is in allowlist
- Check for typos in domain configuration
- Verify referrer handling settings
Mobile app issues
Symptom: Videos don’t play in mobile app
Possible causes:
- WebView not sending referrer
- App domain not configured
Solutions:
- Enable
allowNoReferrer
- Add app’s WebView domain to allowlist
- Check SDK initialization
Partner/embed issues
Symptom: Videos don’t play on partner sites
Solution:
- Add partner domain to allowlist
- Use wildcard if multiple subdomains
- Consider separate API keys for partners
Next steps
