Skip to main content
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, 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:
​
Cookie
string
required
Your Knoq session token. Pass the session cookie value exactly as your browser stores it for knoq.one.
​
Origin
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.
​
Content-Type
string
required
Must be application/json on all POST and DELETE requests that include a body.
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.

​
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. 
curl https://knoq.one/api/managed-agents/sessions \
  -H "Cookie: <your-session-cookie>" \
  -H "Origin: https://knoq.one"
A successful response returns a JSON object containing your sessions: 
{
  "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.
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.

​
Error responses

Status codeWhat it meansWhat to do
401 UnauthorizedYour session cookie is missing or the session has expired.Re-authenticate by signing in to Knoq and obtaining a fresh session token.
403 ForbiddenYour 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.
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.