> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knowlify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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      |

<Warning>
  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.
</Warning>

## 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](/api-reference/errors) for the full status code reference.