Skip to main content
POST
JavaScript
The mint. Your backend authenticates a visitor, asserts who they are, and trades that assertion for a short-lived bearer token the browser uses against the widget host.
Session creation is server-to-server only. This endpoint takes your API key, and your API key must never reach a browser. The browser gets exactly one thing out of this flow: the token in spec.token.

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, so ACME_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:
Now no prompt injection can convince the agent to call a tool against someone else’s accountId. The model never sees the parameter at all.

Revoke a widget session

Kill the token before it expires.

List widget sessions

Filter by widget, tenant, subject, or state.

Create a widget

The widget this session is minted against.

Store and use secrets

How secret interpolation works everywhere else.

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"

Body

application/json

Create widget session request.

spec
object
required

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

metadata
object

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
object[]

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

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

secrets
object[]
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.