Skip to main content
Leases add time-limited access control to content keys. When enabled, the key server issues a lease on first key request and validates it on subsequent requests. Revoking a lease immediately stops playback — without re-encrypting the video.

Enable leases

Set LEASE_TTL_MS to enable:
Leases require authentication. If neither AUTH_JWT_SECRET nor AUTH_JWKS_URL is set, leases are disabled regardless of LEASE_TTL_MS.

How leases work

  1. Player calls POST /keys/leases with the content ID and auth token
  2. Key server extracts the viewer ID from the JWT sub claim, creates a lease, and returns the lease ID + TTL
  3. Player sends X-Lease-Id header on every GET /keys/:contentId request
  4. Key server validates the lease on each request — if expired or revoked, returns 403
  5. Player renews the lease at 75% of TTL via POST /keys/leases/renew

Revoking access

Revoke by viewer

Revoke all active leases for a viewer (e.g., when they cancel their subscription):

Revoke by lease ID

Revoke a specific lease:

Revoke via database

For bulk operations, update the database directly:

What happens when a lease is revoked

  1. The player’s next key request (or lease renewal) gets a 403 response
  2. The player emits a KEY_LEASE_EXPIRED error
  3. Playback stops — the player cannot fetch new keys
See Player Leases for how to handle this in your UI.

Configuration

Cleanup

Expired leases accumulate over time. The key server runs a background cleanup task every hour, deleting leases that expired more than 24 hours ago. For Postgres deployments, you can also run cleanup manually: