Authentication

Every server API request carries one library's private key, and acts on that library only.

Base URLCopy Anchor Link

All server API endpoints live under:

https://api.octavideo.tech/api/v1

Successful responses wrap their payload in data, and list responses add meta with pagination. See Errors for the error format and Pagination and limits for paging.

The private keyCopy Anchor Link

Each library has its own private key. It starts with ovk_ and gives access to that one library: its videos, its collections and its playback OTPs. A key never reaches another library, so give each project or customer its own library.

To get the key:

1. Open your library in the console.
2. Go to API & embeds → Custom Backend.
3. Under Private key, select Copy.

The console shows the key masked and never puts it on screen. If the browser blocks copying, the console tells you so.

Send the keyCopy Anchor Link

Send the key in the AccessKey header on every request:

AccessKey: ovk_your_private_key

This request lists the first page of videos in the library. Each example reads the key from the OCTAVIDEO_KEY environment variable:

curl "https://api.octavideo.tech/api/v1/videos" \
  -H "AccessKey: $OCTAVIDEO_KEY"

A missing or invalid key returns 401 with the code unauthorized. The response doesn't say which, so check that the header name is exactly AccessKey and that the key belongs to the library you expect.

{
  "error": {
    "code": "unauthorized",
    "message": "unauthorized",
    "request_id": "01JBQ7Z9X2R3M4N5P6Q7S8T9V0"
  }
}

Keep the key on your serverCopy Anchor Link

The private key can upload, change and play every video in the library. Treat it like a database password:

• Store it in an environment variable or a secrets manager, never in your source code.
• Call the server API from your backend only. Never put the key in a web page, a browser script or a mobile app.
• Give your browser the result instead: for playback, your server requests an OTP and hands the page an embed_url. See Secure playback.

Rotate the keyCopy Anchor Link

If the key leaks, or someone who had it leaves your team, replace it:

1. Go to API & embeds → Custom Backend.
2. Select Regenerate key… and confirm with Regenerate key.
3. Copy the new key and update it on your server.

The old key stops working as soon as the new one is created, so requests that still use it get 401. Update your servers right away.

What's nextCopy Anchor Link