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 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.

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.

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.

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.
• 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 with the request already written.

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

Troubleshooting

Next steps

• Navigation: the other part every action depends on.
• Turn an action on or off and test it: run one action to check that requests are authenticated.
• Identity verification: tell the agent who the user is.