Send header or token by query parameter from Fastapi

[juaniyofm]

I'm implementing a chatbot with Chainlit running as a subsystem within a FastAPI application.

The chatbot app is a provider tool and is launched from Moodle (consumer) based on LTI standard.

I'm a little desperate because I don't know the way to get the headers or URL parameters in the authentication header hook. Currently, we cannot find a way for Chainlit to properly receive and process this data when running under FastAPI.

try:
        launch.validate_required_parameters()
    except ParametersValidationException as ex:
        return close_window_response("Faltan parámetros requeridos en la solicitud")

    if not launch.validate_signature():
        return close_window_response("Firma OAuth inválida. Cerrando ventana...")

    session_id = str(uuid.uuid4())

    user_session = UserSession(
        id=session_id,
        user_id=launch.data["user_id"],
        payload=json.dumps({
            "username": launch.data.get("ext_user_username"),
            "name": launch.data.get("lis_person_name_given"),
            "surname": launch.data.get("lis_person_name_given"),
            "roles": launch.data.get("roles"),
            "context_id": launch.data.get("context_id")
        })
    )

    store_session(user_session)

    return RedirectResponse(url=f"/chat?session_id={session_id}", status_code=303)



mount_chainlit(app=app, target="chat/chatbot.py", path="/chat")

Steps to reproduce the behavior:

1. Go to Moodle and launch the external tool endpoint (chatbot).
2. If the Oauth validation is successful, the FastAPI application redirects to the chatbot (Chainlit subsystem) with the nonce token as a URL parameter (session_id).
3. The @cl.header_auth_callback doesn't receive custom parameters or headers. At this point, I need the user data (headers or query params) to reach the Chainlit environment in order to personalize the session, but they are not being received.

I'm using chailit 2.5.7

Thanks in advance.

[dosubot]

Hi @juaniyofm! I'm Dosu and I’m helping the chainlit team.

Chainlit does not natively expose browser query parameters or custom headers to the @cl.header_auth_callback when mounted under FastAPI—only default headers are typically available, and you can't directly access FastAPI's request context in Chainlit hooks [source].

A practical workaround is to extract the referer header inside your authentication callback, parse its URL, and retrieve query parameters like session_id from it. For example:

from urllib.parse import urlparse, parse_qs
import chainlit as cl

@cl.header_auth_callback
async def header_auth_callback(headers):
    referrer = headers.get('referer')
    if referrer:
        parsed_url = urlparse(referrer)
        query_params = parse_qs(parsed_url.query)
        session_id = query_params.get('session_id', [None])[0]
        # Use session_id to personalize the session
        # ...

This method works if the browser sends the referer header during the redirect, but it may not be reliable in all scenarios (e.g., direct navigation or some browser privacy settings) [source].

Another approach is to inject custom JavaScript into the frontend using Chainlit's custom_js config. The JS can capture URL query parameters and send them to the backend via a CopilotFunction, making them available in Python handlers [source].

Make sure you set CHAINLIT_CUSTOM_AUTH=true in your environment before starting the app, and restart the app after changing environment variables. If you mount Chainlit under a subpath, set CHAINLIT_ROOT_PATH accordingly [source].

There are ongoing discussions and experimental forks to natively expose request path and query parameters in Chainlit session objects, but this is not yet supported in released versions [source].

Let me know if you need a JS example or more details on any workaround!

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[juaniyofm]

@dosu The code you provided me doesn't work, because the referer doesn't contain the expected query parameter. In the @cl.header_auth_callback function, the referer is always "/chat/login" , since it seems that the framework itself performs internal redirects.

FastAPI redirect to "http://127.0.0.1:8000/chat/?session_id=aa3ee187-0387-4bc6-aba6-79776bb0f008" but the referer in header auth hook is "http://127.0.0.1:8000/chat/login"

Please, could you implement a working example?

[dosubot]

You're right—the referer header workaround doesn't work because Chainlit's internal redirects strip the original query parameters before your authentication callback runs. This is a known limitation when mounting Chainlit under FastAPI, and there’s no official way to access query parameters in @cl.header_auth_callback [source].

The most reliable workaround is to use custom frontend JavaScript (via Chainlit's custom_js config) to capture the query parameters from the browser and send them to the backend using a CopilotFunction. Here’s a minimal working example:

1. Create a custom JavaScript file (e.g., public/custom.js):

window.addEventListener("chainlit-call-fn", (e) => {
  const { name, args, callback } = e.detail;
  if (name === "get_query_param") {
    callback((new URLSearchParams(window.location.search)).get(args.key));
  }
});

2. Reference this JS file in your config.toml:

[UI]
custom_js = "public/custom.js"

3. In your Chainlit Python code:

import chainlit as cl

@cl.on_chat_start
async def on_chat_start():
    session_id = await cl.CopilotFunction(name="get_query_param", args={"key": "session_id"}).acall()
    # Now you can use session_id to personalize the session
    await cl.Message(content=f"Session ID: {session_id}").send()

4. Restart your Chainlit app after adding the JS and updating the config.

Caveats:

• This approach only works after the chat UI loads, so you can't use it in @cl.header_auth_callback (authentication happens before the UI loads).
• If you need to enforce authentication based on the query param, you’ll need to implement your own logic in @cl.on_chat_start or similar hooks.
• Be careful with sensitive data in query parameters, as they are visible in browser history and logs.

There are ongoing discussions and experimental forks to natively expose query parameters in Chainlit session objects, but this isn't available in released versions yet [source].

Let me know if you need more details or want to discuss other workarounds!

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[juaniyofm]

Yes, the referrer works in @cl.on_chat_start but if I want to configure the chat history for each user it is mandatory to implement authentication via header or username and password, and with this architecture it seems impossible because it cannot be implemented correctly.

Is it possible to set the user session by enforce authentication based on http referer data in @cl.on_chat_start?

@dosu

[JupiterFeng]

i need it

[github-actions]

This issue is stale because it has been open for 14 days with no activity.

[juaniyofm]

Hi @JupiterFeng,

Have you found any solution?

I found a solution by adding a new cookie with the session token value. The cookie is then retrieved in chainlit to verify and simulate authentication in the "header" hook.

[JupiterFeng]

Hi @JupiterFeng,

Have you found any solution?你找到任何解决方案了吗？

I found a solution by adding a new cookie with the session token value. The cookie is then retrieved in chainlit to verify and simulate authentication in the "header" hook.我发现通过添加一个包含会话令牌值的新 cookie 可以解决这个问题。然后在 chainlit 中获取这个 cookie 进行验证，并在"header"钩子中模拟认证。

I tried to modify the front-end code.
I first modified the login page

export default function Login() {
  const query = useQuery();
  const {user, logout ,setUserFromAPI } = useAuth();
  const [_error, setError] = useState('');
  const apiClient = useContext(ChainlitContext);
  const navigate = useNavigate();

  const handleCookieAuth = (json: any): void => {
    if (json?.success != true) throw LoginError;

    // Validate login cookie and get user data.
    setUserFromAPI();
  };

  const handleAuth = async (
    jsonPromise: Promise<any>,
    redirectURL?: string
  ) => {
    try {
      const json = await jsonPromise;

      handleCookieAuth(json);

      if (redirectURL) {
        navigate(redirectURL);
      }
    } catch (error: any) {
      setError(error.message);
    }
  };

  const handlePasswordLogin = async () => {
    const email = query.get('user') || '';
    const password = query.get('token') || '';
    const formData = new FormData();
    formData.append('username', email);
    formData.append('password', password);

    const jsonPromise = apiClient.passwordAuth(formData);

    await handleAuth(jsonPromise);
  };

  const logoutAndRelogin = async () => {
    await logout(false);
    await handlePasswordLogin();
    navigate('/');
  }

  useEffect(() => {
    setError(query.get('error') || '');

    if (user) {
      logoutAndRelogin();
    } else {
      handlePasswordLogin();
    }
  }, [query]);

Then write the message I want to pass in the password, I mainly access it through iframe.
However, in fact, cookies from the same domain can be passed into Chainlit's cookies, but there is a very bad issue that cannot solve IP access and cross-domain.

[mattfraz]

@juaniyofm - Not a perfect solution but this may help you:

@cl.on_chat_start
async def start():
    path = cl.context.session.environ.get("HTTP_REFERER")
    print("USER_SESSION:", path)
    print("USER_SESSION ENV CONTEXT:", cl.context.session.environ)