Authentication

All authenticated endpoints require an Authorization header. LynxVizion supports two authentication methods.

API Key Authentication

API keys are the recommended method for server-to-server and script usage.

Format: Authorization: lvz_live_<64 hex chars>

curl https://api.lynxvizion.com/api/videos \
  -H "Authorization: lvz_live_abcdef1234567890..."

Key Management

• Create: POST /api/keys — returns the full raw key (shown once)
• List: GET /api/keys — returns key metadata (prefix only)
• Deactivate: PATCH /api/keys/\{key_id\} — set is_active: false
• Delete: DELETE /api/keys/\{key_id\} — permanently removes the key

See the API Keys reference for full details.

Key Format

lvz_live_<64 hex characters>

Keys are stored as SHA-256 hashes. The raw key is only returned once at creation time. If lost, delete and create a new one.

Key Prefix

Each key has a visible prefix (lvz_live_abcdef12...) for identification without exposing the full key.

JWT Authentication (Clerk)

JWTs are used by the frontend web application and SDKs. Tokens are issued by Clerk.

Format: Authorization: Bearer <clerk-jwt>

curl https://api.lynxvizion.com/api/videos \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

How It Works

1. User authenticates with Clerk (Google OAuth, GitHub OAuth, or email code)
2. Frontend calls getToken() from Clerk’s useAuth() hook
3. Token is sent as Bearer <token> in the Authorization header
4. Backend verifies the JWT signature against Clerk’s JWKS endpoint
5. The Clerk user ID (sub claim) is resolved to the internal user ID

User ID Mapping

Clerk user IDs (user_39IIz...) are mapped to internal UUIDs via Clerk’s external_id field. This mapping is cached in-memory on the API server for performance.

The API returns a user context object:

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "clerk_user_id": "user_39IIzAbCdEfGhIjK",
  "auth_type": "clerk"
}

Unauthenticated Endpoints

Some endpoints do not require authentication:

Endpoint	Description
GET /api/health	API health check
GET /api/shared-reports/\{share_hash\}	View a shared report by hash
GET /api/playback/thumbnail/\{job_id\}	Video thumbnail (presigned redirect)
HEAD /api/playback/stream/\{job_id\}	Check if HLS stream exists
GET /api/playback/stream/\{job_id\}	HLS manifest with presigned segment URLs
GET /api/playback/direct	Direct MP4 playback (presigned redirect)

Error Responses

401 Unauthorized

Returned when the Authorization header is missing, malformed, or contains an invalid/expired credential.

{
  "detail": "Missing Authorization header"
}

{
  "detail": "Token expired"
}

{
  "detail": "Invalid or inactive API key"
}

403 Forbidden

Returned when you try to access a resource that doesn’t belong to your account.

{
  "detail": "Storage path does not belong to this user"
}