Authentication

Every request to https://api.cognitivx.io resolves to a single user (and, when relevant, an org). There are three ways to prove who you are:

• An API key (icog_...) for servers, scripts, CI, agents, and the MCP server.
• A JWT access token issued by sign-in, for the same /api routes.
• Session cookies set by the global SSO at auth.cognitivx.io, for browser apps.

API and SDK integrations almost always want an API key. Browser apps on a cognitivx.io subdomain get cookies for free. The sections below cover each, plus the icog.app cross-origin handoff and OAuth sign-in.

Which should I use

Quick rule: if your code runs on a server, use an API key. If it runs in a browser on cognitivx.io, use cookies. Only reach for the handoff or raw OAuth when you are building the auth surface itself.

API keys

An API key is the simplest credential: a long-lived string scoped to one user. Create keys at developers.cognitivx.io/keys. The full key is shown once, at creation. Store it in a secret manager, never in client-side code.

A key looks like icog_ followed by a URL-safe token. Only the SHA-256 hash and the first 8 characters (key_prefix, for example icog_abc) are stored, so a lost key cannot be recovered. Revoke and reissue instead.

Sending a key

Both header forms are accepted and equivalent:

curl https://api.cognitivx.io/api/me \
  -H "X-API-Key: icog_YOUR_KEY"

curl https://api.cognitivx.io/api/me \
  -H "Authorization: Bearer icog_YOUR_KEY"

A value starting with icog_ is treated as an API key whether you send it via X-API-Key or Authorization: Bearer. Use whichever your HTTP client makes easiest.

Managing keys over the API

You can also mint, list, and revoke keys programmatically. These endpoints are authenticated with a JWT access token (a logged-in user session), not with an API key, since they manage credentials for a user.

Create a key

Mint a personal API key. The plaintext key is returned only on this response.

POST /api/auth/api-keys

Auth: Authorization: Bearer <JWT access token>

curl -X POST https://api.cognitivx.io/api/auth/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "prod"}'

import { keys } from "@cognitivx/sdk";

const created = await keys.create({ name: "prod" });
console.log(created.key); // icog_... shown once, store it now

{
  "id": "8f3c2b1a-1e4d-4a9c-9b2e-7c1d2f3a4b5c",
  "name": "prod",
  "key_prefix": "icog_abc",
  "created_at": "2026-06-16T08:30:00Z",
  "last_used_at": null,
  "key": "icog_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Errors — 401 if the JWT is missing, expired, or invalid. 422 if name is missing.

List keys

GET /api/auth/api-keys

Auth: Authorization: Bearer <JWT access token>

Returns each key's metadata. The full key is never returned after creation, so key is absent here; use key_prefix and name to identify keys.

curl https://api.cognitivx.io/api/auth/api-keys \
  -H "Authorization: Bearer YOUR_JWT"

import { keys } from "@cognitivx/sdk";

const all = await keys.list();
all.forEach((k) => console.log(k.name, k.key_prefix, k.last_used_at));

[
  {
    "id": "8f3c2b1a-1e4d-4a9c-9b2e-7c1d2f3a4b5c",
    "name": "prod",
    "key_prefix": "icog_abc",
    "created_at": "2026-06-16T08:30:00Z",
    "last_used_at": "2026-06-16T09:14:51Z"
  }
]

Revoke a key

DELETE /api/auth/api-keys/{key_id}

Auth: Authorization: Bearer <JWT access token>

curl -X DELETE https://api.cognitivx.io/api/auth/api-keys/8f3c2b1a-1e4d-4a9c-9b2e-7c1d2f3a4b5c \
  -H "Authorization: Bearer YOUR_JWT"

import { keys } from "@cognitivx/sdk";

await keys.revoke("8f3c2b1a-1e4d-4a9c-9b2e-7c1d2f3a4b5c");

Returns 204 No Content. Revocation is immediate.

Errors — 404 if no key with that id belongs to you.

Org context

Keys and tokens resolve to a user, and a user can belong to organizations. To act inside an org with a JWT, send X-Org-ID: <org-uuid>; membership is checked and a non-member gets 403. Without the header, calls fall back to your active org. An org-scoped API key always forces its own org, so you do not send X-Org-ID with one.

JWT access tokens

A successful sign-in (POST /api/auth/signin, OAuth, or the handoff) yields a short-lived JWT access token. It authenticates the same /api routes as an API key:

curl https://api.cognitivx.io/api/recall \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
  -H "Content-Type: application/json" \
  -d '{"query": "billing decisions", "limit": 5}'

Access tokens expire (401 "Token expired"). When they do, mint a fresh one with POST /api/auth/refresh using your refresh-token cookie, or sign in again. For non-interactive code that should not expire, use an API key instead.

Session cookies

Browser apps served from a cognitivx.io subdomain (console, developers, docs, and so on) do not handle tokens. The global SSO at auth.cognitivx.io sets an httponly refresh-token cookie scoped to the shared cognitivx.io parent domain, so every sibling subdomain is signed in at once.

Send cross-subdomain fetch calls with credentials and the cookie rides along:

await fetch("https://api.cognitivx.io/api/me", {
  credentials: "include",
});

The cookie is SameSite=Lax, Secure, and HttpOnly, so JavaScript cannot read it. It is sent automatically; you never copy it into a header. Cookie auth only works within *.cognitivx.io. For a different registrable domain such as icog.app, use the handoff below.

OAuth providers

auth.cognitivx.io/login supports sign-in with Google, GitHub, and X (Twitter). The backend drives a standard OAuth 2.0 authorization-code flow (with PKCE/S256 for X). You normally do not call these endpoints directly; the hosted login page does. They are documented here for teams building a custom sign-in surface.

Start the flow

Get the provider consent URL, then redirect the browser to it.

GET /api/auth/oauth/{provider}/authorize

Auth: none (public).

curl "https://api.cognitivx.io/api/auth/oauth/google/authorize"

{
  "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&state=...",
  "redirect_uri": "https://api.cognitivx.io/api/auth/oauth/google/callback"
}

Redirect the user to authorize_url. The state parameter is a signed, short-lived token that carries your originating origin and (for X) the PKCE verifier, so you do not manage either yourself.

Errors — 400 if the provider is unknown or not configured on the server.

Handle the callback

After the user consents, the provider redirects back to GET /api/auth/oauth/{provider}/callback?code=...&state=.... The backend exchanges the code, finds or creates the matching user, sets the refresh-token cookie, and issues a 302 redirect to your frontend at:

/auth/callback?token=<access_token>&new=<0|1>

Your frontend reads token (the JWT access token) and new (1 for a freshly created account, 0 for an existing one) off the query string. From there you hold a normal access token and, on cognitivx.io, the session cookie.

The icog.app handoff

Cookies scoped to cognitivx.io cannot be read by icog.app, which is a separate registrable domain. To carry an existing session across that boundary, the backend mints a one-shot token on the source origin and exchanges it for a cookie on the target origin.

curl -X POST https://api.cognitivx.io/api/auth/handoff/mint \
  -H "Content-Type: application/json" \
  --cookie "refresh_token=YOUR_SESSION_COOKIE" \
  -d '{"target_origin": "https://icog.app"}'

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

curl -X POST https://api.cognitivx.io/api/auth/handoff/exchange \
  -H "Content-Type: application/json" \
  -H "Origin: https://icog.app" \
  -d '{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'

{
  "user_id": "c2d4e6f8-1234-5678-9abc-def012345678",
  "email": "[email protected]",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Errors

Authentication failures share the standard error shape. Every error body is {"detail": ...}, and every response carries an X-Request-ID header you can quote in a bug report.

What's next

• Run your first authenticated call.
• Browse the API reference for every endpoint.
• Plug iCog into Claude or Cursor with the MCP tools.