Skip to main content

Authentication

Authentication & Security

HesedVid uses two authentication methods designed for different use cases.

Tip

Most integrations only need API keys. WorkOS sessions are used for the web dashboard.

Authentication Methods

For programmatic access and server-to-server communication:

2. WorkOS Sessions (Dashboard)

Used for web dashboard authentication:

  • OAuth/SAML SSO support
  • Session-based authentication
  • Automatic refresh handling
  • Organization membership validation

Note

WorkOS sessions are managed automatically by the dashboard. You don’t need to implement this for API access.

Private Video Playback

Videos with allowPublicAccess: false require signed URLs for playback.

How It Works

  • Client requests video: User wants to watch a private video

  • Server validates access: Your backend checks user permissions

  • Server requests signed URL: Call HesedVid API to get signed playback URL

  • Client plays video: Use the signed URL in any HLS player

  • Implementation

    Token Security

    Signed URLs include JWT tokens with:

    PropertyDescriptionExample
    Video IDLocked to specific videovid_AbCdEfGh
    ExpirationTime-limited access1-24 hours
    IssuerVerified by our CDNhesedvid
    AudienceIntended recipientVideo public ID

    Caution

    Never generate signed URLs directly in client-side code. Always use your backend to validate access first.

    Security Best Practices

  • Protect API Keys

    • Store in environment variables
    • Never commit to version control
    • Never expose in client-side code
  • Use Appropriate Key Scopes

    • Environment-scoped for production
    • Full access only for admin tasks
    • Rotate keys regularly
  • Implement Access Control

    • Validate user permissions server-side
    • Log access attempts
    • Monitor for unusual patterns
  • Secure Video Delivery

    • Use signed URLs for private content
    • Set appropriate expiration times
    • Consider IP restrictions for sensitive content
  • CORS Configuration

    Our infrastructure handles CORS automatically:

    ServiceCORS PolicyHeaders
    CDNPermissiveAccess-Control-Allow-Origin: *
    APIRestrictedConfigured origins only
    WorkerPermissiveAll methods allowed

    Tip

    Video playback works from any domain. API calls require authentication regardless of origin.

    Rate Limiting

    API endpoints are rate-limited per organization:

    Endpoint TypeLimitWindow
    General API10,0001 hour
    Upload URLs1001 hour
    Analytics1,0001 hour
    Video PlaybackUnlimited-

    Rate limit headers:

    X-RateLimit-Limit: 10000
    X-RateLimit-Remaining: 9999
    X-RateLimit-Reset: 1640995200

    Troubleshooting

    Common Authentication Issues

    ErrorCauseSolution
    401 UnauthorizedMissing/invalid API keyCheck Authorization header
    403 ForbiddenValid key, wrong scopeUse correct environment key
    429 Too Many RequestsRate limit exceededImplement backoff
    Token expiredSigned URL timeoutRequest fresh URL

    Debug Authentication

    Terminal window
    # Test API key
    curl -I https://api.hesedvid.com/v1/api/org_123/environments \
    -H "X-Api-Key: YOUR_API_KEY"
    # Check rate limits
    curl -I https://api.hesedvid.com/v1/api/org_123/videos \
    -H "X-Api-Key: YOUR_API_KEY" \
    | grep X-RateLimit