Revoke a widget session
The kill switch. Tokens stop working now, streams close in seconds, secrets are wiped. Terminal.
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.
Related
Delete a widget session
Delete a tenant's sessions
List widget sessions
Create a widget session
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.
Body
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 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.