Create a widget session
Mint a visitor’s session server-to-server. You get the bearer token once, here, and never again.
The token appears once
spec.token is returned by this call and by nothing else. Reads omit it. Hand it to the browser and forget it: the token is short-lived, and the widget refreshes it at the widget host without involving your backend. spec.tokenExpiresAt bounds the token; spec.expiresAt bounds the session itself, after which it moves to STATE_EXPIRED and refreshes stop.
Return info.host alongside the token. It is the authoritative hostname the token works against, and clients must not construct it themselves.
Tenant and subject are assertions
You do not create tenants; you assert them.spec.tenant.id is your identifier for the visitor’s org (acme-corp), and the assertion upserts the tenant record in the workspace. spec.subject names the person within the tenant, in your namespace. A subject without a tenant is rejected with InvalidArgument.
The session carries the assertion to every conversation it creates, which is what scopes conversation listing at the widget host to the visitor’s tenant.
Secrets make the agent act as the visitor
Attach per-visitor credentials (say, a token your backend minted against your own API) and every conversation the session creates carries them. Values are encrypted at rest, interpolated into tool-call headers server-side, and never returned by any API. On a name clash, session secrets beat workspace and tool set secrets, soACME_API_TOKEN means this visitor’s token, not the shared one.
pinnedParameters locks tool arguments
A pinned parameter is removed from the JSON schema the model sees, and its value is overwritten server-side on every call. Pin the values a visitor must not influence:
accountId. The model never sees the parameter at all.
Related
Revoke a widget session
List widget sessions
Create a widget
Store and use secrets
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Body
Create widget session request.
WidgetSessionSpec is the configuration of a session, fixed at mint.
CreateOperationMetadata contains the user-provided fields for creating an operation. Read-only fields (id, account_id, workspace_id, created_at, profile_id) are excluded since they are set by the server.
Secrets to attach to the session.
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 bearer token returned at mint is short-lived and refreshed at the widget host; the session row is what makes revocation possible.
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 WidgetSessionInfo provides read-only server-derived data about a session.
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.