Authentication

How to authenticate calls to the Knowlify HTTP API

Overview

The Knowlify HTTP API supports two authentication methods. External integrations should use API keys; the JWT path is reserved for first-party dashboard sessions.

Method	Header	Use case
API key	X-API-Key: kn_<64 hex>	Server-to-server, scripts, scheduled jobs
Supabase JWT	Authorization: Bearer <jwt>	First-party dashboard / SDK sessions

API keys grant full access to your account or organization billing and should never be shipped in client-side code or committed to source control. Treat them like passwords.

API keys

API keys are 67 characters long: a kn_ prefix followed by 64 hexadecimal characters.

X-API-Key: kn_4f3c8b1a9e7d2f5a6b8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3

Issuing and rotating keys

1. Open the Developer tab in your dashboard.
   • Personal scope: create.knowlify.com/p/dashboard?tab=developer
   • Organization scope: create.knowlify.com/org/{slug}/dashboard?tab=developer (owner or admin only)
2. Click Generate API key. The key is shown once — copy it into your secret manager immediately.
3. Each account has a single active key. Generating a new key revokes the previous one immediately.
4. Click Revoke key to invalidate the current key without issuing a replacement.

Personal vs. organization keys

• Personal keys authenticate as your user. Jobs and credits are charged to your personal workspace.
• Organization keys authenticate as the org. The org membership is pinned to the key — if the creator is removed from the org, the key stops working. Jobs and credits are charged to the org workspace.

When a request body includes an org_id and the key is org-scoped, the two must match or the request is rejected with 400.

Allowlist

For safety, API keys currently authorize only the following endpoints:

• POST /v1/videos — create one or more video generation jobs
• GET /v1/videos/{uuid} — poll the status of a job
• POST /v1/edits — submit an edit on an existing video
• GET /v1/edits/{edit_id} — poll an edit
• POST /v1/edits/{edit_id}/revert — undo the most recent completed edit

All other endpoints require an authenticated dashboard session. Reach out if you need additional endpoints exposed.

Supabase JWT

First-party clients (the Knowlify dashboard, the Python SDK in interactive mode) authenticate with a Supabase JWT:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The token is validated as HS256 against the authenticated audience. JWT callers may optionally pass org_id in the request body — the server verifies active membership before honoring the scope.

Failure modes

Status	When
401 Unauthorized	Header missing, malformed, or refers to a revoked key
403 Forbidden	JWT caller is not an active member of the requested org_id
400 Bad Request	org_id in body does not match the org the API key belongs to

See Errors for the full status code reference.