Sessions and trust

A session lets a signed-in user of your app talk to one agent from your page, while your org API key stays on your server.

Skills for your coding agent

See it running: Plain HTML counter, Conversation list

Your server creates a session so a signed-in user of your app can talk to one agent from your page. It calls Mindset with your org API key and passes the response to the browser, where the SDK uses it.

Where	What it holds
Your server	The org API key. It is admin-grade and never reaches a browser
The browser	The session: an opaque credential for one agent, one user, one org and one environment, kept in memory

The key is the authorization, so the agent needn't be shared with the user in the Hub. It does need Embedded in your own product ticked and an active version. See How agents are started and reached.

Why it matters#

Your users talk to the agent without a Mindset account, and the API key never leaves your server. A session is limited to one agent, one user and one environment, so one taken from a browser reaches nothing else.

How long it lasts#

While the page is open, the SDK renews its own short-lived access token, so you write no renewal code.

Event	What happens
Not used within about 20 minutes of creation	The session expires
Idle for 7 days	The session ends
30 days after creation	The session ends, however active it is
The page reloads	The session is gone, because the SDK keeps it only in memory

When the SDK can't continue, it calls your page's getSession function again for a new session. A new agent version reaches the user on their next turn, but the agent's connections, widgets and functions are fixed for the life of the session.

Who the agent thinks the user is#

Mindset takes your server's word for who the user is, and creating a session finds or creates that user in your org. Your server names them one of two ways:

	`email`	`externalId`
Use it when	The person might also use Mindset directly	Your users exist only in your app, or you'd rather Mindset didn't hold their email
Matching	Case-insensitive. One email is one person in your org, however they arrive	Exact, case included. It never merges with an email identity
Signing in to Mindset	The same user as their Mindset sign-in, if they have one	Never signs in to Mindset

Mindset doesn't check that an email's mailbox exists. Pick one form per user and keep it: switching gives you two users with two histories.

What the user can reach#

A session reaches only what the agent's run needs, such as model calls, tool calls and this user's conversations with the agent. It is refused on every management surface, even for an org admin. Two agents on one page need two sessions.

Access ends from the user's next turn when you untick Embedded in your own product, turn off the agent's Available switch, or remove the user from your org.

Keep secrets on your server#

A session works from any page that holds it, so treat it like a short-lived password for that user. Its contents change between releases, so don't decode, rebuild or store it.

Everything your page gives the agent lives in the browser, where the user and every script on the page can read it. That includes page tools, situational awareness and pass-through values.

Without a backend#

The element can sign a visitor in with Google for the same kind of session. That needs the website in the environment's Allowed websites list (Settings → Environments), self-signup on for your org, and the agent ticked for both The Hub and Embedded in your own product.

For the code, see Put an agent on your page and the Session API. To start an agent from your backend with no browser, see Start it from your server or a schedule.