Skip to main content
GET

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

id
string
required

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
object
required

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

spec
object
required

WidgetSessionSpec is the configuration of a session, fixed at mint.

state
enum<string>
required
read-only

The current lifecycle state of the session. Output only. Sessions are created STATE_ACTIVE; use :revoke to end one early.

Available options:
STATE_UNSPECIFIED,
STATE_ACTIVE,
STATE_EXPIRED,
STATE_REVOKED,
STATE_EXHAUSTED
secrets
object[]
required
read-only

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.

info
object

WidgetSessionInfo provides read-only server-derived data about a session.

credentials
object

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.