Get a widget session by ID
Retrieves a widget session. The bearer token is never returned on reads.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Session ID. Accepts the canonical wsess_… form or the external_id:<value> form.
Response
OK
WidgetSession is a delegated, narrowed credential for one visitor's use of a widget, minted server-to-server by the customer's backend. The session carries all customer-asserted context — tenant, subject, labels, secrets — and every conversation (objective) created through the widget inherits it. The browser renews short-lived bearer tokens at the widget host with RenewWidgetSession, authenticated by its existing token. Renewal preserves this bounded grant and does not extend its hard expiry.
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
WidgetSessionSpec is the configuration of a session, fixed at mint.
The current lifecycle state of the session. Output only. Sessions are created STATE_ACTIVE; use :revoke to end one early.
STATE_UNSPECIFIED, STATE_ACTIVE, STATE_EXPIRED, STATE_REVOKED, STATE_EXHAUSTED Names of the secrets attached to the session. Values are write-only: provided at creation, encrypted at rest, and interpolated into tool-call headers server-side — never returned by any API.
WidgetSessionInfo provides read-only server-derived data about a session.
Present only on creation. The same envelope is returned by RenewWidgetSession on the widget host. Omitted on reads, lists, and revocation. Existing spec.token/spec.token_expires_at and info.host remain populated on creation for v1 compatibility and agree with these credentials.