Public References and Secure Bootstrap

Treat a public reference as an identifier and a bootstrap assertion as a credential. An app can configure a public externalAgentRef in its client, but only an authenticated server should mint the signed assertion that vouches for the current user. The SDK then establishes a session whose token must be handled as a bearer credential.

The browser, server, agent, result, session, and error path mark distinct integration boundaries.

Tell identifiers and credentials apart

A public reference points to a resource in the external-agent runtime. The SDK’s stored session record includes public refs such as externalAgentRef, sessionRef, and, when present, externalUserRef or workspaceBindingRef. Those refs do not replace user authentication, and they do not turn a client-side request into an authorized one.

The bootstrap assertion has a different role. The getting-started guide describes it as a short string produced and signed by your backend to vouch for the current end user. The SDK asks for it through getBootstrapAssertion; it does not create or sign it. Keep the credential that signs assertions on the server and authenticate the user at the endpoint that mints one.

Session storage introduces a third value to protect: the session token. getStoredSession() returns public session metadata without the token, but the stored record used by a RuntimeStorage adapter includes it. Anyone able to read that storage can act as the session until it expires or is revoked. The SDK defaults to in-memory storage; persistence is a deliberate security and product decision.

Trace one browser session

For an internal request portal, suppose an employee signs in, opens a service assistant, and asks for the status of request SR-204. The app may expose a public agent reference to its browser client. The server still needs to verify the employee before minting an assertion, and the assistant must receive only the policy and tools configured for its job.

1. Authenticate the user on the server. Tie the assertion request to the app’s signed-in user; do not accept a user identity supplied only in browser data.
2. Return an assertion, not the signing secret. The SDK callback calls the authenticated endpoint and returns the assertion string. Never include the credential that signs it in the client bundle or response.
3. Create or reuse a session. ensure() obtains an assertion when needed and stores the session token. If a valid stored session already exists, it is reused and the assertion callback is not called.
4. Choose where to store the session. The default is in memory. If persistence is required, evaluate which scripts and users can read the adapter; use a separate storageKey for each agent embedded on the same page.
5. End the session intentionally. On logout, call the server-side revocation method and remove locally stored session data according to the app’s lifecycle.

Boundary check (fictional portal)
Browser configuration: Public externalAgentRef only.
Server check: Employee is authenticated before assertion minting.
Session: ensure() returns a public sessionRef; the signing credential stays on the server.
Storage choice: In-memory for this short visit; no persistent session adapter.
Record consulted: The approved service-system record SR-204 has status “Under review.”
Result: The employee sees the “Under review” status after the agent completes the lookup; no assertion-signing secret or session token is displayed.

The sample assumes the agent has a separate, authorized way to look up the request. The reference, assertion, and session do not grant a tool that the agent policy does not expose.

Review the stored state

Check the exact value each layer can read: browser configuration, assertion endpoint response, SDK callback, adapter contents, and the object returned by getStoredSession(). Do not infer that the token is absent merely because the public getter omits it. For complete setup details, read getting started and sessions and storage. Continue with embedding an agent and workspace bindings.