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

# Authenticating requests to the Knoq API

> Knoq's API uses session-based authentication. Learn how to send authenticated requests using your session cookie and the required Origin header.

Every request to the Knoq API must be made on behalf of an authenticated user. Knoq does not issue standalone API keys — instead, authentication relies on the session cookie that your browser receives when you sign in. This means the API is designed for use from authenticated browser sessions, though you can also drive it programmatically by forwarding valid session credentials from a script or integration layer.

## How authentication works

When you sign in at [knoq.one](https://knoq.one), your browser receives a session cookie. On every API request, Knoq's server validates that cookie to confirm your identity and determine which organisation your request is scoped to. If the session is missing or has expired, the request is rejected with a `401 Unauthorized` response.

All API endpoints under `/api/managed-agents/` require a valid session. The authentication check runs on every request before it reaches the route handler, so you will receive a `401` immediately if the cookie is absent or invalid.

## Making authenticated requests

To call the Knoq API programmatically — for example, from a script, a backend service, or an integration test harness — you must supply the session credentials that would normally be managed by your browser. Every authenticated request must include:

<ParamField header="Cookie" type="string" required>
  Your Knoq session token. Pass the session cookie value exactly as your browser stores it for `knoq.one`.
</ParamField>

<ParamField header="Origin" type="string" required>
  Must be set to `https://knoq.one` on all mutating requests (`POST`, `DELETE`). Knoq's CSRF guard rejects mutating requests whose `Origin` header does not match the application's own origin. Read-only requests (`GET`) do not require this header, but including it is harmless.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json` on all `POST` and `DELETE` requests that include a body.
</ParamField>

<Note>
  The easiest way to obtain a session token for scripted use is to sign in to
  Knoq in your browser, open DevTools, navigate to **Application → Cookies**
  for `knoq.one`, and copy the session token value. Treat this value like a
  password — it grants full access to your account.
</Note>

## Example authenticated request

The following example lists all sessions for your active organisation. It passes your session cookie in the `Cookie` header and the required `Origin` header.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://knoq.one/api/managed-agents/sessions \
    -H "Cookie: <your-session-cookie>" \
    -H "Origin: https://knoq.one"
  ```

  ```python Python theme={null}
  import requests

  cookies = {
      "knoq_session": "<your-session-token>",
  }

  headers = {
      "Origin": "https://knoq.one",
  }

  response = requests.get(
      "https://knoq.one/api/managed-agents/sessions",
      cookies=cookies,
      headers=headers,
  )

  print(response.json())
  ```

  ```typescript TypeScript (fetch) theme={null}
  const response = await fetch("https://knoq.one/api/managed-agents/sessions", {
    headers: {
      Cookie: "<your-session-cookie>",
      Origin: "https://knoq.one",
    },
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

A successful response returns a JSON object containing your sessions:

```json theme={null}
{
  "sessions": [
    {
      "id": "3f2a1b4c-...",
      "title": "How do I set up the GitHub connector?",
      "updatedAt": "2025-01-15T10:32:00.000Z"
    }
  ]
}
```

## Organisation context

All API calls are scoped to your active organisation. Knoq reads your current organisation from your session — every query filters by both your user ID and your organisation ID, so you can only see and modify data that belongs to your org.

If you are a member of multiple organisations, your active org is determined by which organisation your session was established with. To switch the active organisation, sign in to Knoq on the web and use the org switcher in the user menu, or call `POST /api/auth/switch-org`. Any subsequent API calls will be scoped to the newly active organisation.

<Tip>
  If you are building a multi-org integration, be deliberate about which
  session token you use for each request. A session token issued for Org A
  cannot read or modify data belonging to Org B — you will receive a `404`
  rather than a `403` to avoid leaking the existence of cross-org resources.
</Tip>

## Error responses

| Status code        | What it means                                                                                                     | What to do                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized` | Your session cookie is missing or the session has expired.                                                        | Re-authenticate by signing in to Knoq and obtaining a fresh session token.                                               |
| `403 Forbidden`    | Your plan does not include the feature you are requesting, or the CSRF `Origin` check failed on a mutating route. | Check that you are including `Origin: https://knoq.one`. If the origin is correct, review your organisation's plan tier. |

<Note>
  The Knoq API is currently designed for use from authenticated browser
  sessions. A standalone API key authentication method for server-to-server
  integration — without requiring a browser sign-in — is on the roadmap.
</Note>