Authentication

The RAG Chats API uses JWT (JSON Web Tokens) for authentication. This guide covers how to obtain and use tokens.

Authentication Methods

There are two ways to authenticate:

• JWT Tokens — For user-authenticated requests (dashboard, management)
• API Keys — For agent-specific operations (queries, widget)

JWT Token Authentication

Step 1: Login

Obtain access and refresh tokens by logging in:

Response

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Step 2: Use the Access Token

Include the access token in the Authorization header:

-purple-500">curl https://api.ragchats.ai/api/agents/ \
  -H -green-500">"Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

Step 3: Refresh the Token

Access tokens expire after 1 hour. Use the refresh token to get a new one:

-purple-500">curl -X POST https://api.ragchats.ai/api/auth/token/refresh/ \
  -H -green-500">"Content-Type: application/json" \
  -d '{
    -green-500">"refresh": -green-500">"your_refresh_token"
  }'

Response

{
  "access": "new_access_token..."
}

Token Expiration

API Key Authentication

For agent-specific operations like querying, use an API key instead of JWT tokens. This is simpler for server-to-server integrations.

Creating an API Key

1. Go to your agent's Developer tab
2. Click API Keys
3. Click Generate New Key
4. Copy the key (it's only shown once)

Using an API Key

-purple-500">curl -X POST https://api.ragchats.ai/api/agents/BOT_ID/query/ \
  -H -green-500">"Authorization: Bearer YOUR_API_KEY_HERE" \
  -H -green-500">"Content-Type: application/json" \
  -d -green-500">'{"message-green-500">": "Hello-green-500">"}'

Logout

Invalidate tokens when the user logs out:

-purple-500">curl -X POST https://api.ragchats.ai/api/auth/logout/ \
  -H -green-500">"Authorization: Bearer your_access_token"

Security Best Practices

• Store tokens securely — Use httpOnly cookies or secure storage
• Never expose in client code — API keys should only be used server-side
• Rotate keys regularly — Generate new API keys periodically
• Use HTTPS — All API requests must use HTTPS
• Handle token refresh — Implement automatic token refresh before expiry

Error Responses

{
  "error": "token_expired",
  "message": "Access token has expired",
  "details": {
    "expired_at": "2024-01-15T10:30:00Z"
  }
}