# Authentication

Authentication is the part of a Web Agent that makes its actions run as the user who is signed in to your app. The analysis finds how your app keeps a session and writes the code that sends that session with every request. You see it in the agent's [**Actions**](https://auth.faustine.ai/go?to=%2Fweb-assistants) tab, in the **Assistant** group, as **Authentication**.

This page is about your app's own sign-in. To tell the agent which of your users it is talking to, see [Identity verification](https://docs.faustine.ai/web-agents/identity-verification/).

## How it works

The agent has no credentials of its own. Its actions run in the user's browser, inside your page, so they can read what your app reads: a token in storage, or the cookies the browser already sends.

The analysis writes one function, `authHeaders()`, in a file named `authentication.js`. It returns the headers your API expects. Every action passes its request through that function before it is sent, and the action's own headers win when both set the same one. A change to how your app signs requests is therefore made in one place.

A request that fails comes back to the agent as an error with its HTTP status. If the request lands on a sign-in page because the session expired, the agent is told that the user is not signed in.

## What the analysis records

Open **Authentication** in the **Actions** tab to see three things.

| Part | What it is |
| --- | --- |
| **How your app authenticates** | A description, in words, of what the analysis found. |
| **Send credentials with requests** | A switch. When it is on, requests include the browser's cookies (`credentials: 'include'`). |
| `authentication.js` | The body of `authHeaders()`. Only the body can be edited. |

Under them, `runtime.js` shows the fixed code that every agent shares: how the headers are merged and how a response becomes a result or an error. It is read-only. The Advanced editor lists the same file as `sdk-runtime.js`.

## Token in a header

An app that stores a token and sends it as a header gets a body that reads the token the way the app does. For an app that keeps a bearer token in local storage, the body looks like this. The key name comes from your code.

```js filename="authentication.js"
const token = localStorage.getItem('<TOKEN_KEY>');
return token ? { Authorization: `Bearer ${token}` } : {};
```

## Cookie session

An app that signs in with a session cookie needs no header. `authHeaders()` returns an empty object and **Send credentials with requests** is on, so the browser attaches the cookie.

If your API is on a different origin from the page, it has to allow credentialed requests from that origin in its CORS policy, as it already does for your app.

## Change the authentication

Change it when your app changes how it signs in, for example from a stored token to an httpOnly cookie. There are three ways.

- Run an update or a re-analysis. See [Keep the agent up to date](https://docs.faustine.ai/web-agents/keep-up-to-date/).
- Edit the body of `authHeaders()` or the switch in the **Actions** tab, then select **Save changes**.
- Select **Doesn't look right? Fix it in an interactive session** to open [the Advanced editor](https://docs.faustine.ai/web-agents/advanced-editor/) with the request already written.

The change is saved to the draft. Your site gets it when you publish a version.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Every action fails with status `401` | `authHeaders()` does not read the session the way your app does now. | Compare the body with your app's API client, or run an update. |
| Actions fail on a cookie-session app, and the same requests work in your app | **Send credentials with requests** is off. | Turn it on, save and publish. |
| Actions report that the user is not signed in | The request was redirected to a sign-in page because the session expired. | The user signs in to your app again. |

## Next steps

- [Navigation](https://docs.faustine.ai/web-agents/navigation/): the other part every action depends on.
- [Turn an action on or off and test it](https://docs.faustine.ai/web-agents/test-an-action/): run one action to check that requests are authenticated.
- [Identity verification](https://docs.faustine.ai/web-agents/identity-verification/): tell the agent who the user is.