Authentication

The IntelliRag API supports two authentication methods depending on the client type. Both methods use the Authorization header with a Bearer token.

API keys

API keys are the recommended authentication method for programmatic access - scripts, CI pipelines, the CLI, and the MCP server. API keys are created in the IntelliRag dashboard and are scoped to a single tenant.

Pass the API key in the Authorization header:

curl https://api.intellirag.io/v1/workspaces \
  -H "Authorization: Bearer rag_xxxx"

API keys use the rag_ prefix. Keep them secret - anyone with the key has full access to your tenant’s data.

Creating an API key

1. Log in to the IntelliRag dashboard.
2. Navigate to Settings > API Keys.
3. Click Create API Key, give it a name, and copy the key.

The full key is only shown once at creation time. Store it securely.

OAuth2 / JWT

Browser-based clients (the dashboard, admin portal) use OAuth2 authorization code flow with Ory Hydra as the identity provider. After completing the OAuth2 flow, the client receives a JWT access token.

Pass the JWT in the Authorization header:

curl https://api.intellirag.io/v1/workspaces \
  -H "Authorization: Bearer eyJhbGciOi..."

JWT tokens include the tenant_id in their claims and expire after a configurable period. The dashboard handles token refresh automatically.

This method is primarily for browser applications. For programmatic access, use API keys instead.

Index tokens

Index tokens are short-lived, narrowly scoped tokens used by the indexer during indexing runs. They are not created manually - the indexer obtains one automatically by calling the index token endpoint with an API key.

Obtaining an index token

curl -X POST https://api.intellirag.io/v1/auth/index-token \
  -H "Authorization: Bearer rag_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"remote_url": "https://github.com/org/repo"}'

The remote_url field tells the API which repository the indexer will write to. The server resolves the corresponding tenant_id, workspace_id, and repo_id from the API key and the registered remote URL.

Response

{
  "token": "idx_xxxx",
  "tenant_id": "t_xxxx",
  "workspace_id": "w_xxxx",
  "repo_id": "r_xxxx",
  "expires_at": "2024-01-01T01:00:00Z"
}

Field	Description
token	The index token to use for batch write operations
tenant_id	Resolved tenant ID
workspace_id	Resolved workspace ID
repo_id	Resolved repository ID
expires_at	Token expiration time (short-lived, typically 1 hour)

The repository must already exist in the dashboard - the indexer does not auto-create repositories.

Security notes

• tenant_id is server-controlled. The tenant ID is always derived from the authenticated credential (API key or JWT claims). It is never taken from the request body, query parameters, or path parameters.
• API keys are tenant-scoped. An API key can only access data belonging to the tenant it was created under.
• All requests require authentication. There are no public endpoints. Unauthenticated requests receive a 401 Unauthorized response.