Skip to main content

​
Overview

Khoj supports multiple authentication methods:
  1. API Tokens - For programmatic access (recommended for API usage)
  2. OAuth with Google - For user login via web interface
  3. Magic Links - Passwordless email authentication
Most API endpoints require the authenticated scope and will redirect unauthenticated requests to the login page.

​
API Token Authentication

API tokens provide secure programmatic access to your Khoj account. This is the recommended method for API integrations.

​
Generate an API Token

Generate a new API token for your account. 
curl -X POST https://app.khoj.dev/api/auth/token \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"token_name": "My API Token"}'
Request
​
token_name
string
Optional name for the token to help you identify it later
Response
​
token
string
The generated API token (store this securely)
​
name
string
The name you assigned to the token
Example Response
{
  "token": "kh_1a2b3c4d5e6f7g8h9i0j",
  "name": "My API Token"
}
Store your API token securely. It provides full access to your account and cannot be retrieved again. If lost, you’ll need to generate a new token.

​
Using API Tokens

Include your API token in the Authorization header of your requests: 
curl https://app.khoj.dev/api/search?q=example \
  -H "Authorization: Bearer kh_YOUR_API_TOKEN"

​
List Your Tokens

View all active API tokens for your account.
cURL
curl https://app.khoj.dev/api/auth/token \
  -H "Cookie: session=YOUR_SESSION_COOKIE"
Response: Array of token objects with names and creation dates

​
Delete a Token

Revoke an API token when it’s no longer needed.
cURL
curl -X DELETE https://app.khoj.dev/api/auth/token?token=kh_TOKEN_TO_DELETE \
  -H "Cookie: session=YOUR_SESSION_COOKIE"
​
token
string
required
The token string to delete

​
OAuth Authentication

Khoj supports OAuth 2.0 authentication with Google.

​
OAuth Login Flow

  1. Initiate Login - Redirect user to /api/auth/login
  2. OAuth Redirect - User authenticates with Google
  3. Callback - Google redirects to /api/auth/redirect
  4. Session Created - User session established

​
Endpoints

​
GET /api/auth/login

Initiates the OAuth flow by redirecting to Google’s authorization page. 
curl https://app.khoj.dev/api/auth/login

​
GET /api/auth/redirect

Callback endpoint for OAuth. Google redirects here after authentication.
​
code
string
Authorization code from Google
​
next
string
URL to redirect to after successful authentication

​
GET /api/auth/logout

Ends the user session. 
curl https://app.khoj.dev/api/auth/logout \
  -H "Cookie: session=YOUR_SESSION_COOKIE"

​
OAuth Metadata

Retrieve OAuth configuration details. 
curl https://app.khoj.dev/api/auth/oauth/metadata
Response 
{
  "google": {
    "client_id": "YOUR_GOOGLE_CLIENT_ID",
    "redirect_uri": "https://app.khoj.dev/api/auth/redirect"
  }
}
Magic links provide passwordless authentication via email. Request a magic link to be sent to your email.
cURL
curl -X POST https://app.khoj.dev/api/auth/magic \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
​
email
string
required
Email address to send the magic link to
Response: 200 OK if email was sent successfully
Rate limited to 10 requests per 24 hours per user and 20 requests per 24 hours per email.
This endpoint is called automatically when the user clicks the magic link. 
GET /api/auth/magic?code=VERIFICATION_CODE&email=[email protected]
​
code
string
required
Verification code from the magic link
​
email
string
required
Email address associated with the magic link
Response: Redirects to home page (/) on success

​
Session Management

Khoj uses session cookies for web-based authentication. The session is stored in the user field of the request session.

​
Check Authentication Status

Verify your authentication and get user info. 
curl https://app.khoj.dev/api/health \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Response 
{
  "email": "[email protected]"
}

​
Get User Information

Retrieve detailed information about the authenticated user. 
curl https://app.khoj.dev/api/v1/user \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Response
​
email
string
User’s email address
​
username
string
Username
​
photo
string
URL to user’s profile photo
​
is_active
boolean
Whether the user has an active premium subscription
​
has_documents
boolean
Whether the user has indexed any documents
​
khoj_version
string
Version of Khoj server
Example
{
  "email": "[email protected]",
  "username": "user123",
  "photo": "https://example.com/photo.jpg",
  "is_active": true,
  "has_documents": true,
  "khoj_version": "1.0.0"
}

​
Security Best Practices

1

Use HTTPS

Always use HTTPS in production to protect tokens in transit.
2

Store Tokens Securely

Never commit tokens to version control. Use environment variables or secure secret management.
3

Rotate Tokens Regularly

Generate new tokens periodically and delete old ones.
4

Use Minimal Scopes

Only request the permissions your application needs.
5

Monitor Token Usage

Regularly review active tokens and revoke any that are no longer needed.

​
Anonymous Mode

Khoj can be run in anonymous mode with --anonymous-mode flag, which disables authentication entirely. This is only recommended for local development or single-user deployments.
Anonymous mode bypasses all authentication checks. Do not use in production with public access.

Build docs developers (and LLMs) love

Get started for freeTalk to us