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

**Skill for your coding agent:** [`mindset-embed/SKILL.md`](https://docs.mindset.ai/skills/mindset-embed/SKILL.md)

**Skill for your coding agent:** [`mindset-uiless/SKILL.md`](https://docs.mindset.ai/skills/mindset-uiless/SKILL.md)

Builders work from a coding agent and operators from an AI client, both through the MCP server, or in the Studio. In Mindset, an agent is a prompt and a model, held to an order by a script when needed. It uses connections to outside systems, operations on them, functions and widgets. Every change is a version, and every execution is a run. Every piece sits on one security and compliance layer: the org sets its posture once, and every agent works under it, with the audit trail and, once an admin turns it on, personal data redaction. The platform runs in your own cloud (AWS, GCP or Azure) or is hosted by Mindset. Your app reaches agents through the SDK, your server through the API, and people through the Hub and schedules. Highlighted: Your app, Your server.

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](https://docs.mindset.ai/docs/environments), 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](https://docs.mindset.ai/docs/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](https://docs.mindset.ai/docs/page-tools#pass-through-values).

> **Danger:** Mindset hides pass-through values from the model, but they are never secret.

## 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](https://docs.mindset.ai/docs/put-an-agent-on-your-page) and the [Session API](https://docs.mindset.ai/docs/session-api). To start an agent from your backend with no browser, see [Start it from your server or a schedule](https://docs.mindset.ai/docs/start-it-from-your-server).