User authentication

This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).

Generate a signed JSON Web Token (JWT) on your backend and send it with each request to keep user data private.

What user authentication enables

Secure user tokens allow Agent Studio to:

Associate each conversation with a user.
Store and retrieve memory per user.
Restrict access so users can only read their own conversations and memory.
Support multi-user apps with personalized experiences.

Without a secure JWT, Agent Studio can’t identify users. As a result, it can’t scope conversations and memory per user.

JWT authentication flow

User authentication uses JSON Web Tokens (JWTs) to identify users securely:

Key points

JWTs are generated on your backend server, never in frontend code
JWTs contain a user identifier in the sub (subject) claim
Agent Studio validates the JWT signature using your authentication key
All data is automatically scoped to the authenticated user

Set up user authentication

Create an authentication key in the dashboard

Go to Agent Studio Settings
Go to User authentication and click Create authentication key
In the creation box:
1. Enter a descriptive name (for example, “Production authentication key”)
2. Choose the scope:
- All agents: the key works for all agents in your application
- Specific agents: select which agents this key applies to
Click Create
Copy the authentication key: it starts with sk-alg-...
From the authentication keys table, note the value in the ID column
Save both values securely:
- Key ID (from the ID column): store in ALGOLIA_KEY_ID environment variable
- Authentication key (the full sk-alg-... value): store in ALGOLIA_SECRET_KEY environment variable

In the dashboard, select Setup guide for details about using authentication keys.

Keep your authentication key secure. Don’t commit it to version control or expose it in frontend code. Use environment variables or a secrets management system.The authentication key can be found in the authentication keys table.

Generate JWTs on your backend

Create an endpoint on your backend that generates JWTs for authenticated users. The token must include:

sub claim: Your user’s unique identifier
exp claim: Token expiration timestamp
kid header: Your Algolia key ID

If you’re using the JavaScript or Python API client, you can use the built-in forgeSecuredUserToken helper instead of building the JWT manually.

import jwt
from datetime import datetime, timedelta
import os

@app.post("/api/algolia-token")
def get_algolia_token(current_user: User):
    """Generate a secure user token for the authenticated user."""
    payload = {
        "sub": current_user.id,  # User identifier from your authentication system
        "exp": int((datetime.utcnow() + timedelta(hours=24)).timestamp())
    }

    token = jwt.encode(
        payload,
        os.environ["ALGOLIA_SECRET_KEY"],
        algorithm="HS256",
        headers={"kid": os.environ["ALGOLIA_KEY_ID"]}
    )

    return {"token": token}

Security requirements:

Generate tokens only on your backend server
Require users to authenticate first
Never expose your authentication key (ALGOLIA_SECRET_KEY) in frontend code
Use HTTPS for all token transmission
Set appropriate token expiration times

Use tokens in API requests

Include the JWT in the X-Algolia-Secure-User-Token header when making Agent Studio API requests:

Command line

# Example: Start a conversation with user authentication
curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/completions" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \
  -H "X-Algolia-Secure-User-Token: $SECURE_USER_TOKEN" \
  -H "Content-Type: application/json" \
-d '{
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

Frontend implementation example:

JavaScript

// Get token from your backend
const userToken = await fetch("/api/algolia-token", {
	method: "POST",
	credentials: "include", // Include session cookies
})
	.then((r) => r.json())
	.then((d) => d.token);

// Use token in Agent Studio requests
const appID = "ALGOLIA_APPLICATION_ID";
const apiKey = "ALGOLIA_SEARCH_API_KEY";
const agentId = "AGENT_ID";

const response = await fetch(
	`https://${appID}.algolia.net/agent-studio/1/agents/${agentId}/completions`,
	{
		method: "POST",
		headers: {
			"X-Algolia-Application-Id": appID,
			"X-Algolia-API-Key": apiKey,
			"X-Algolia-Secure-User-Token": userToken, // User-scoped access
		},
		body: JSON.stringify({
			messages: [{ role: "user", content: "Hello" }],
		}),
	},
);

If you use the InstantSearch Chat widget with agentId, pass the token with requestOptions.headers:

<Chat
  agentId="AGENT_ID"
  requestOptions={{
    headers: {
      "X-Algolia-Secure-User-Token": userToken,
    },
  }}
/>

Use this option only with the built-in agentId path. If you use a custom transport, add the secure user token to that transport’s headers.

Security

Follow these security recommendations to reduce the risk of leaked keys, improperly scoped users, and expired tokens in production.

Token expiration

Set reasonable expiration times (for example, 24 hours)
Implement token refresh logic in the frontend
Handle expired token errors gracefully

Authentication key management

Store authentication keys in environment variables or secrets managers
Rotate keys periodically (create new keys and delete old ones from the dashboard)
Use different keys for different environments (development, staging, production)
Use specific agent scoping when possible to limit key access

User validation

Always verify user identity on your backend before generating tokens
Include only necessary user identifiers in the sub claim
Don’t include sensitive user data in JWT payloads (they’re not encrypted)

HTTPS requirement

Always transmit tokens over HTTPS
Secure your backend token generation endpoint
Validate Cross-Origin Resource Sharing (CORS) settings to prevent unauthorized domains from accessing tokens

Common patterns

Token refresh

Handle token expiration by refreshing tokens automatically, without prompting users to sign in again:

JavaScript

async function getValidToken() {
	let token = localStorage.getItem("algolia_token");
	let expiry = localStorage.getItem("algolia_token_expiry");

	// Check if token is expired or will expire soon (within 5 minutes)
	if (!token || !expiry || Date.now() > parseInt(expiry) - 5 * 60 * 1000) {
		// Fetch new token from backend
		const response = await fetch("/api/algolia-token", {
			method: "POST",
			credentials: "include",
		});
		const data = await response.json();

		token = data.token;
		expiry = Date.now() + 24 * 3600 * 1000; // 24 hours from now

		localStorage.setItem("algolia_token", token);
		localStorage.setItem("algolia_token_expiry", expiry.toString());
	}

	return token;
}

Error handling

Handle authentication errors appropriately:

JavaScript

try {
	const response = await fetch(apiUrl, {
		headers: {
			"X-Algolia-Secure-User-Token": await getValidToken(),
		},
	});

	if (response.status === 401) {
		// Token invalid or expired - clear and retry
		localStorage.removeItem("algolia_token");
		localStorage.removeItem("algolia_token_expiry");
		// Redirect to login or retry with new token
	}
} catch (error) {
	console.error("Authentication error:", error);
}

Common issues

“Invalid signature” error:

Verify your authentication key (the full sk-alg-... value) matches the one from the dashboard
Ensure you’re using HS256 algorithm
Check that the kid header matches your key ID (from the ID column in the authentication keys table)

“Token expired” error:

Implement token refresh logic
Check that your server’s clock is synchronized (JWT uses timestamps)
Verify the exp claim is set correctly

User data not being scoped:

Confirm you’re including the X-Algolia-Secure-User-Token header
Verify the sub claim contains a valid user identifier
Check that the token is being generated with the correct user ID

​What user authentication enables

​JWT authentication flow

​Key points

​Set up user authentication

​Security

​Token expiration

​Authentication key management

​User validation

​HTTPS requirement

​Common patterns

​Token refresh

​Error handling

​Common issues

​See also

What user authentication enables

JWT authentication flow

Key points

Set up user authentication

Security

Token expiration

Authentication key management

User validation

HTTPS requirement

Common patterns

Token refresh

Error handling

Common issues

See also