Skip to main content

​
Overview

Share links enable teams to share videos with external stakeholders securely. Each share link can be configured with expiration dates, password protection, and download permissions.

​
Creating Share Links

Team members with member role or higher can create share links:
1

Generate Token

A unique 32-character token is generated for each share link to ensure unpredictability
2

Configure Access

Set optional expiration date, password protection, and download permissions
3

Share URL

The generated link can be shared with anyone via email, chat, or other channels

​
Share Link Options

Expiration Date

Set links to expire after a specific number of days (1, 7, 30, etc.)

Password Protection

Require a password to access the shared video

Download Permission

Control whether viewers can download the video file

View Tracking

Automatically count how many times the link has been accessed

​
Password Protection

Share links support secure password protection:

​
Password Security

Passwords are hashed using bcrypt before storage. Plain text passwords are never stored in the database.

​
Brute Force Protection

Multiple security layers prevent unauthorized access:
1

Failed Attempt Tracking

Each incorrect password attempt is recorded on the share link
2

Lockout Trigger

After 5 failed attempts, the link is temporarily locked
3

Lockout Duration

Locked links cannot be accessed for 10 minutes
4

Automatic Reset

Failed attempt counter resets after successful access or password change
Share links are locked after 5 failed password attempts. The lockout lasts 10 minutes and cannot be bypassed except by updating the link settings.

​
Password Limits

  • Maximum password length: 256 characters
  • Empty passwords are treated as no password protection
  • Password can be added, changed, or removed at any time

​
Rate Limiting

Share link access is protected by multi-level rate limiting:

Global Limit

600 access grants per minute across all share links (8 shards)

Per-Token Limit

120 access grants per minute per individual share link

Password Failures

10 password failures per minute per share link
Rate limiting is implemented using a fixed window algorithm via the Convex rate limiter component.

​
Access Grant System

Share links use a two-step access process:

​
Step 1: Validation

When a user visits a share link URL:
  • Token is validated (must exist and not be expired)
  • Video status is checked (must be “ready”)
  • Password requirement is communicated to the user

​
Step 2: Grant Issuance

After validation (and optional password entry): 
// Access grant flow
1. Validate rate limits (global + per-token)
2. Check expiration date
3. Verify video is ready
4. Check password if protected
5. Issue temporary access grant token
6. Increment view count
The issued grant token provides:
  • Temporary access to the video
  • Time-limited validity (configurable)
  • No password re-entry required during validity period

​
Share Link States

Token doesn’t exist or video has been deleted

​
Managing Share Links

Teams can view and manage all share links for a video:

​
Link List View

Each share link displays:
  • Creation date and creator name
  • Expiration status (active or expired)
  • Password protection indicator
  • View count
  • Download permission status

​
Updating Links

Share link settings can be modified after creation:
  • Change expiration date or remove expiration
  • Add, change, or remove password
  • Toggle download permissions
  • View count cannot be modified
Changing a share link password resets the failed attempt counter and removes any lockout.

​
Deleting Links

Deleting a share link:
  • Immediately invalidates the link
  • Deletes all associated access grant tokens
  • Cannot be undone
  • Video remains accessible via other share links or team access

​
View Count Tracking

Each share link tracks usage metrics:
  • Incremented: When an access grant is successfully issued
  • Displayed: In the share link management interface
  • Persistent: Never resets automatically
  • Per-Link: Each share link has independent tracking
View counts help teams understand engagement and decide when links can be revoked.

​
Share Link Security

Multiple security measures protect shared videos:

​
Token Generation

  • 32-character random tokens
  • Uniqueness validated before creation
  • Maximum 5 retry attempts if collision occurs
  • Cryptographically random generation

​
Access Validation

Every access attempt validates:
  1. Token exists in database
  2. Link hasn’t expired
  3. Video is in “ready” state
  4. Not currently locked out (if password-protected)
  5. Password is correct (if required)
  6. Rate limits not exceeded

​
Grant Token Security

Access grant tokens are:
  • Separate from share link tokens
  • Time-limited (default expiration)
  • Stored in a separate table
  • Indexed for fast validation
  • Automatically cleaned up after expiration

​
Share Links vs. Public Links

Use public links for permanent sharing within your organization. Use share links for temporary external sharing with more control.

​
Integration with Comments

Users accessing videos via share links:
  • Can add comments if authenticated
  • Must use share grant token for comment creation
  • Comments persist after grant expires
  • User identity comes from Clerk authentication

​
Performance Considerations

Share link validation is optimized for speed:

​
Database Indexing

  • by_token: Fast share link lookup
  • by_video: List all links for a video
  • Grant token index for validation

​
Caching Strategy

  • Share link status can be cached (check expiration client-side)
  • Grant tokens validated on every request
  • View count updates are non-blocking
Share link access is designed to be fast, even under high load, with multiple layers of rate limiting and caching.

Build docs developers (and LLMs) love

Get started for freeTalk to us