Authentication

VIDTREO Player uses API keys to authenticate video requests. This guide explains how to obtain and securely configure your API key.

Obtaining Your API Key

Follow these steps to create a secure API key for the player:

1. Sign in to the VIDTREO Dashboard
2. Go to Environment — Use an existing environment or create a new one
3. Navigate to API Keys tab — Open the API Keys section
4. Create a new API key — Click "Create New Key"
5. Assign permissions — Select only the Get video permission
6. Assign domains (Recommended for security) — Specify which domains can use this API key
   • This is optional but highly recommended for security
   • You can add specific domains (e.g., myapp.com, *.myapp.com)
   • Requests from other domains will be rejected

Using Your API Key

You'll need both the API key and the video ID to play a video:

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
></vidtreo-player>

The API key is sent as an Authorization header in requests to authenticate and access videos from your environment.

Environment Variables (Build Tools)

For projects using build tools (Vite, Webpack, etc.):

# .env
VITE_VIDTREO_API_KEY=vt_live_xxxxxxxxxxxxxxxxxxxx

<vidtreo-player
  video-id="your-video-id"
  api-key="import.meta.env.VITE_VIDTREO_API_KEY"
></vidtreo-player>

# .env.local
NEXT_PUBLIC_VIDTREO_API_KEY=vt_live_xxxxxxxxxxxxxxxxxxxx

<vidtreo-player
  video-id="your-video-id"
  api-key={process.env.NEXT_PUBLIC_VIDTREO_API_KEY}
></vidtreo-player>

Security Features

VIDTREO provides comprehensive security features for API key management:

Rate Limits

API keys are subject to rate limits to prevent abuse:

• Requests are rate-limited per API key
• Exceeding limits returns a 429 Too Many Requests error
• Rate limits vary by plan and environment

Access Logs

All API key usage is logged:

• Track which videos are accessed
• Monitor request patterns
• Review access history in the dashboard
• Identify suspicious activity

Permission Scoping

When creating an API key, assign only the Get video permission:

• Limits the key to video retrieval only
• Prevents unauthorized actions
• Follows the principle of least privilege

Environment Isolation

API keys are scoped to specific environments:

• Production keys access production videos
• Development keys access development videos
• Environments are isolated for security

Security Best Practices

Do's ✅

• Use environment variables — Never hardcode API keys
• Use different keys for development and production
• Assign minimal permissions — Only grant "Get video" permission
• Configure domain restrictions — Limit which domains can use the key
• Rotate keys regularly especially if compromised
• Use .gitignore to exclude .env files
• Monitor access logs — Review usage patterns regularly

Don'ts ❌

• Never commit API keys to version control
• Never expose keys in client-side JavaScript without domain restrictions
• Don't share keys between projects or environments
• Don't use production keys for development
• Don't grant unnecessary permissions — Only "Get video" is needed for the player

Domain Restrictions

For additional security, you can restrict API keys to specific domains:

1. Go to Dashboard → API Keys
2. Select your key
3. Add allowed domains (e.g., myapp.com, *.myapp.com)

Requests from other domains will be rejected.

Troubleshooting

Invalid API Key

Error: Failed to fetch video: 401 Unauthorized

Solutions:

• Verify the key is correctly copied (no extra spaces)
• Check if the key is for the correct environment (live vs test)
• Ensure the key hasn't been revoked

Domain Not Allowed

Error: Failed to fetch video: 403 Forbidden

Solutions:

• Add your domain to the allowed list in the dashboard
• For local development, add localhost to allowed domains

Key Expired

Error: Failed to fetch video: 401 Unauthorized

Solutions:

• Generate a new API key from the dashboard
• Update your application with the new key

Proxy Configuration (SSR)

For server-side rendering applications, you may want to proxy API requests to avoid exposing your API key:

// api/vidtreo-proxy.ts (Next.js API Route)
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const videoId = req.query.videoId as string;
  
  const response = await fetch(`https://core.vidtreo.com/api/v1/videos/${videoId}/file`, {
    headers: {
      'Authorization': `Bearer ${process.env.VIDTREO_API_KEY}`,
    },
  });

  if (!response.ok) {
    return res.status(response.status).json({ error: 'Failed to fetch video' });
  }

  const blob = await response.blob();
  res.setHeader('Content-Type', blob.type);
  res.send(Buffer.from(await blob.arrayBuffer()));
}

Then configure the player to use your proxy:

<vidtreo-player
  video-id="your-video-id"
  api-key="proxied"
  backend-url="/api/vidtreo-proxy"
></vidtreo-player>

Next Steps

• Quick Start — Play your first video
• Configuration Options — Explore all options
• Web Component Integration — Detailed integration guide