index4.ai Authentication

Every request is authorised with Authorization: Bearer <token> against https://api.index4.ai/v1. The simplest and recommended credential is a project API key: it is tied to one project, and a project namespace is the unit of isolation for ingested documents and their vectors.

Account-level credentials (an account API key or a login token) are also accepted on the retrieval endpoints, as long as you tell the API which project you mean with an X-Project-ID header. Projects marked as protected reject account-level credentials and accept only their own project key.

Token types at a glance

Token	Prefix	Where it comes from	Use it for	Use it on retrieval endpoints?
Login token (JWT)	— (JWT)	Console login (or POST /login)	Browser session inside the console	✅ with X-Project-ID (not on protected projects)
Account API key	poma_acc_…	Console, or POST /generateApiKey	Automation that needs account-wide access	✅ with X-Project-ID (not on protected projects)
Project API key	poma_proj_gr_…	Console when you create a project, or POST /projects/{projectId}/generateApiKey	Every project-scoped call	✅

The prefix is your fastest sanity check for a project key: it starts with poma_proj_gr_. The Python SDK is project-key only: it validates this prefix locally, rejects poma_acc_… keys, and raises InvalidApiKeyError before the request ever leaves your machine.

The project API key is shown exactly once at project creation. It is not stored in plaintext — if you lose it, rotate the project key (see below).

Get a project API key — the console workflow

The whole provisioning flow happens inside the index4.ai console:

1. Sign in. First visit creates an account.
2. (Optional) Create an organisation if you want the project to be team-owned. Skip this step for a personal project.
3. Create a project: enter a project name, optionally pick an organisation, and confirm.
4. Copy the project API key the dialog hands back. It's shown once. Paste it into your secret manager immediately.

You can later inspect, rotate or delete projects in the console or over the API — see Create a project.

Need to script project creation programmatically — e.g. provisioning one project per customer in a multi-tenant SaaS? Use POST /projects and POST /projects/{projectId}/generateApiKey from the API reference. These docs intentionally don't duplicate it; the console is the supported path for human-operated setup.

Using the credentials

The Python SDK reads the project key from INDEX4AI_API_KEY and validates the prefix at construction time. Direct HTTP callers put the same token in a Bearer header.

curl

export INDEX4AI_API_KEY="poma_proj_gr_…"

curl -s https://api.index4.ai/v1/docs \
  -H "authorization: Bearer $INDEX4AI_API_KEY"

curl (account key)

# Account key or login token: name the project explicitly
curl -s https://api.index4.ai/v1/docs \
  -H "authorization: Bearer $INDEX4AI_ACCOUNT_KEY" \
  -H "X-Project-ID: $PROJECT_ID"

python (requests)

import os, requests

API = "https://api.index4.ai/v1"
H = {"Authorization": f"Bearer {os.environ['INDEX4AI_API_KEY']}"}

r = requests.post(
    f"{API}/search",
    headers={**H, "content-type": "application/json"},
    json={"query": "What changed in the Q3 financial outlook?"},
    timeout=30,
)
print(r.json()["context"])

node

const res = await fetch("https://api.index4.ai/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INDEX4AI_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    query: "What changed in the Q3 financial outlook?",
  }),
});
const { context } = await res.json();

Storing the key

• Treat the project API key like a database password — it grants full read/write/delete access to the project's document namespace.
• Inject via environment variable (INDEX4AI_API_KEY — the name the SDK reads automatically) or your secret manager. Do not commit it.
• One key per project. If you run multiple projects in the same process, pass the key explicitly per client rather than juggling the env var.
• Never use a project API key in browser code. It is a server-side credential. For browser flows, proxy through your backend.

Rotation and recovery

If the key is leaked or lost, issue a new one from the console:

1. Open the project in the index4.ai console.
2. Rotate or regenerate its API key. The dialog hands back a fresh poma_proj_gr_… key.
3. Update your secret manager and deployments with the new key.

Your ingested documents stay in the project. Scripted rotation uses POST /projects/{projectId}/generateApiKey (API reference).

Common errors

Where	Symptom	Cause	Fix
SDK (local)	InvalidApiKeyError at client construction	Token is missing, or has the wrong prefix (e.g. poma_acc_… instead of poma_proj_gr_…)	Use the project key from the console, not an account key.
Server	401	Missing or invalid Authorization header	Check the header name and that the token is present, unquoted, and trimmed.
Server	403	Account-level credential used on a protected project, or the project is not accessible to this credential	Use the project's own API key.
Server	404 from /docs/{docId}	Document is not in this project's namespace	Confirm the doc was ingested into the same project (same key, or same X-Project-ID) you're now querying with.

Next

• Create a project — what a project owns, organisation-scoped projects, and what deletion means.
• Quickstart — first ingest + search round-trip with the project key.