Skip to main content
POST
JavaScript
End a session before its expiry. Revocation moves it to STATE_REVOKED: outstanding tokens stop working immediately, open event streams close within seconds, and the session’s secrets are deleted.

Terminal means terminal

There is no unrevoke. A revoked session never refreshes another token, and the visitor needs a fresh mint from your backend to keep chatting. Wire revocation to the same events that end access in your own product: logout, seat removal, offboarding, a contract ending. This is the session row earning its keep. The token is a bearer credential in a browser you do not control; the row on the server is what lets you take it back.

Revoke keeps the row. Delete removes it.

Revoke and delete both end access and both drop the session’s secrets. The difference is the paper trail: a revoked session stays listable (?state=STATE_REVOKED) with its assertions and activity intact, while delete removes the row. Revoke to end access; delete to clean up.

Delete a widget session

Remove the row once you no longer need the record.

Delete a tenant's sessions

Every session for a tenant, plus their conversations.

List widget sessions

Find the session to kill.

Create a widget session

The re-entry path after a revoke.

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.

Body

application/json

Revoke widget session request.

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.