Signed URLs and Embed Tokens
Every video on AVCaption has an embed token in its URL: https://avcaption.com/watch/{embed_token}. The token is the access credential — anyone with a valid token can play the video, anyone without one gets denied.
For free or public content, you generate one token per video and it lives forever. For paid or gated content, you generate fresh tokens per authenticated session via the REST API.
How tokens work
A token is a short opaque string (32 hex chars by default). Server-side it maps to:
- The video ID
- An optional viewer identifier (used for analytics + dynamic watermark)
- An expiration timestamp
- A list of allowed origins (your domain whitelist)
- Rate limit metadata
When the player requests a stream key, the server validates the token, checks the expiration, checks the request origin, and only then issues the AES-128 key for the next batch.
Per-session tokens via REST API
For paid content, the recommended pattern is:
- User logs in to your application.
- Your application authenticates the user against your DB.
- Your application calls AVCaption’s REST API:
POST /api/v1/embed-tokenwith{video_id, viewer_id, expires_in: 3600}. - AVCaption returns a one-time embed token valid for 1 hour.
- You render the iframe with that token.
- The token expires; if the user refreshes, your app generates a fresh one.
This means a user who copies the iframe URL and shares it gets a token that expires within an hour — useless for redistribution.
Domain whitelisting at the token level
Tokens can be bound to specific origins. A token issued for app.example.com will not work if embedded on pirate-site.com. The browser sends a Referer header on the master playlist request; AVCaption validates it against the whitelist and refuses to issue keys.
Compared to signed URL approaches
Some platforms use signed URLs (HMAC-signed query strings on each segment). AVCaption uses opaque tokens that map server-side to access metadata. Trade-offs:
- Signed URLs — fully stateless, easy to verify at edge. But once a URL is signed, it can’t be revoked until expiration.
- Opaque tokens (AVCaption) — require server-side lookup per stream session, but enable real-time revocation, per-token analytics, and richer access metadata.
For paid content where revocation matters, opaque tokens win. See the embed token vs signed URL glossary entry for a deeper comparison.
Token rotation
For very high-value content, rotate tokens via the API on a schedule:
POST /api/v1/embed-token/rotate
{ "video_id": "abc123" }
This invalidates all existing tokens for that video and issues a new one. Useful after a suspected leak or a chargeback.
When to use which TTL
| TTL | Use case |
|---|---|
| 5 minutes | One-time download-style delivery (paid digital product, single-use review link) |
| 1 hour | Standard authenticated session (member portal, course player) |
| 24 hours | Free public content, marketing video |
| 30 days | Time-limited rental access, monthly bonus content |
Shorter TTLs raise security; longer TTLs reduce token-mint API calls. For most paid-content use cases, 1 hour is the right default.
Get started
Embed tokens are issued automatically on every upload, all tiers. The REST API for per-session token generation is an Enterprise feature — wire it into your auth check and you’ll mint per-session tokens that expire when sessions do. Open a free account, upload one video, and verify the default 24-hour token expires when you expect. Common patterns: per-session tokens for online courses and membership site video.