Authentication
The API key
Every /api/v1/* and /api/v1.1/* request needs an API key in the Authorization header:
Authorization: Bearer vuf_live_<keyid>.<secret>
A key has two halves separated by a dot:
| Part | Role |
|---|---|
keyid | Public identifier. Used server-side only to look the key up. |
secret | The secret half. Shown once at creation; the server stores only its SHA-256 hash. |
Send the whole string, including the vuf_live_ prefix.
curl https://video.pyler.ai/api/v1/usage \
-H "Authorization: Bearer $VUF_API_KEY"
Getting a key
Keys are issued from the dashboard's API Keys tab at video.pyler.ai/account/api-keys.
The plaintext secret is shown once at creation and is never recoverable afterwards. Copy it into your secrets manager before you leave the page. If you lose it, create a new key.
Keep the key out of source control. Put it in an environment variable (the examples in these docs use VUF_API_KEY) and read it at runtime.
Keys belong to an organization
A key identifies your organization, not an individual user. Everything you create or list through it, such as videos, batches, ads, custom summaries and screenings, is scoped to that organization, and GET /api/v1/usage reports that organization's quota.
The same key works on both version roots, /api/v1 and /api/v1.1.
401 vs 403
Authentication failures use the standard error envelope.
| Status | Meaning | What to do |
|---|---|---|
401 | Missing or invalid API key. | Check that the Authorization: Bearer ... header is present and the key is complete. A missing header is the most common cause. |
403 | The key was used on a path outside the public API roots (/api/v1, /api/v1.1). | API keys only work on the public API. Dashboard routes need a browser session. |
Authentication failures carry only detail, no code:
{ "detail": "authentication required" }
{ "detail": "invalid api key" }
{ "detail": "api key not permitted for this path" }
The interactive Swagger UI at video.pyler.ai/api-docs, available after you sign in to the dashboard, has an Authorize button at the top right. Add your key there once and every "Try it out" request sends it automatically. The request panel on each page of this site does the same, and does not keep the key in your browser after you close the tab.