Sign in

v56

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-01142337440.5 KB
WidgetSessionService
Widget Sessions

Create a widget session

Mints a session against a widget and returns the session bearer token (spec.token, returned only on creation) plus the authoritative widget hostname (info.host). Asserting a tenant upserts the tenant record; attached secrets flow to every conversation the session creates.

post/v1/workspaces/{workspaceId}/widget_sessions

Path parameters

workspaceIdstring required
Example:workspace_01HXKD2E5NQM3T9AYWCF133E3Q

Workspace ID.

Request body

workspaceIdstring required

Workspace ID.

Example request

{
  "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  "spec": {
    "widgetId": "wgt_01HXKD2E5NQM3T9AYWCFMZZZBD",
    "tenant": {
      "id": "acme-corp",
      "name": "Acme Corp"
    },
    "subject": {
      "id": "customer-user-42",
      "name": "Jane Doe"
    }
  }
}

Response

OK

state'STATE_UNSPECIFIED' | 'STATE_ACTIVE' | 'STATE_EXPIRED' | 'STATE_REVOKED' | 'STATE_EXHAUSTED' enum required

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

Example response

{
  "metadata": {
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08"
  },
  "spec": {
    "widgetId": "wgt_01HXKD2E5NQM3T9AYWCFMZZZBD",
    "tenant": {
      "id": "acme-corp",
      "name": "Acme Corp"
    },
    "subject": {
      "id": "customer-user-42",
      "name": "Jane Doe"
    }
  },
  "info": {
    "tenant": {
      "id": "tenant_01HXKD2E5NQM3T9AYWCF133E3Q",
      "externalId": "acme-corp",
      "name": "Acme Corp"
    },
    "subject": {
      "id": "subj_01HXKD2E5NQM3T9AYWCFQAZGFV",
      "externalId": "customer-user-42",
      "name": "Jane Doe"
    },
    "host": "k7m2xq9fp4wn.widgets.cadenya.com"
  }
}