cadenya widget-sessions create \
  --widget-id sample \
  --tenant-id sample \
  --subject-id sample

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "labels": {},
    "createdAt": "2023-11-07T05:31:56Z",
    "externalId": "<string>",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08"
  },
  "spec": {
    "widgetId": "wgt_01HXKD2E5NQM3T9AYWCFMZZZBD",
    "tenant": {
      "id": "acme-corp",
      "name": "Acme Corp"
    },
    "subject": {
      "id": "customer-user-42",
      "name": "Jane Doe"
    },
    "token": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "tokenExpiresAt": "2023-11-07T05:31:56Z",
    "pinnedParameters": {}
  },
  "state": "STATE_UNSPECIFIED",
  "secrets": [
    {
      "name": "<string>"
    }
  ],
  "info": {
    "widget": {
      "id": "<string>",
      "name": "<string>"
    },
    "agent": {
      "id": "<string>",
      "name": "<string>"
    },
    "host": "k7m2xq9fp4wn.widgets.cadenya.com",
    "messageCount": 123,
    "tenant": {
      "id": "tenant_01HXKD2E5NQM3T9AYWCF133E3Q",
      "externalId": "acme-corp",
      "name": "Acme Corp"
    },
    "subject": {
      "id": "subj_01HXKD2E5NQM3T9AYWCFQAZGFV",
      "externalId": "customer-user-42",
      "name": "Jane Doe"
    },
    "lastActiveAt": "2023-11-07T05:31:56Z"
  },
  "credentials": {
    "sessionId": "<string>",
    "host": "<string>",
    "token": "<string>",
    "tokenExpiresAt": "2023-11-07T05:31:56Z",
    "sessionExpiresAt": "2023-11-07T05:31:56Z"
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "domain": "api.cadenya.com",
      "reason": "TOKEN_EXPIRED",
      "metadata": {}
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "domain": "api.cadenya.com",
      "reason": "TOKEN_EXPIRED",
      "metadata": {}
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "domain": "api.cadenya.com",
      "reason": "TOKEN_EXPIRED",
      "metadata": {}
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "domain": "api.cadenya.com",
      "reason": "TOKEN_EXPIRED",
      "metadata": {}
    }
  ]
}

Widget Sessions

Create a widget session

Creates a bounded session and returns WidgetSessionCredentials in credentials. For v1 compatibility, spec.token, spec.tokenExpiresAt, info.host, and spec.expiresAt remain populated and agree with credentials. Credentials are creation-only and omitted on reads. Use Cache-Control: no-store. The customer’s backend authenticates the visitor and must provide nonempty spec.tenant.id and spec.subject.id; sessions for that identity share history on the same widget and agent; attached secrets remain server-side. The browser obtains subsequent credentials for this same session with RenewWidgetSession on the widget host, authenticated by its existing session token.

POST

workspaces

{workspaceId}

widget_sessions

cadenya widget-sessions create \
  --widget-id sample \
  --tenant-id sample \
  --subject-id sample

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "labels": {},
    "createdAt": "2023-11-07T05:31:56Z",
    "externalId": "<string>",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08"
  },
  "spec": {
    "widgetId": "wgt_01HXKD2E5NQM3T9AYWCFMZZZBD",
    "tenant": {
      "id": "acme-corp",
      "name": "Acme Corp"
    },
    "subject": {
      "id": "customer-user-42",
      "name": "Jane Doe"
    },
    "token": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "tokenExpiresAt": "2023-11-07T05:31:56Z",
    "pinnedParameters": {}
  },
  "state": "STATE_UNSPECIFIED",
  "secrets": [
    {
      "name": "<string>"
    }
  ],
  "info": {
    "widget": {
      "id": "<string>",
      "name": "<string>"
    },
    "agent": {
      "id": "<string>",
      "name": "<string>"
    },
    "host": "k7m2xq9fp4wn.widgets.cadenya.com",
    "messageCount": 123,
    "tenant": {
      "id": "tenant_01HXKD2E5NQM3T9AYWCF133E3Q",
      "externalId": "acme-corp",
      "name": "Acme Corp"
    },
    "subject": {
      "id": "subj_01HXKD2E5NQM3T9AYWCFQAZGFV",
      "externalId": "customer-user-42",
      "name": "Jane Doe"
    },
    "lastActiveAt": "2023-11-07T05:31:56Z"
  },
  "credentials": {
    "sessionId": "<string>",
    "host": "<string>",
    "token": "<string>",
    "tokenExpiresAt": "2023-11-07T05:31:56Z",
    "sessionExpiresAt": "2023-11-07T05:31:56Z"
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "domain": "api.cadenya.com",
      "reason": "TOKEN_EXPIRED",
      "metadata": {}
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "domain": "api.cadenya.com",
      "reason": "TOKEN_EXPIRED",
      "metadata": {}
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "domain": "api.cadenya.com",
      "reason": "TOKEN_EXPIRED",
      "metadata": {}
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "domain": "api.cadenya.com",
      "reason": "TOKEN_EXPIRED",
      "metadata": {}
    }
  ]
}

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.

Show child attributes

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.

Show child attributes

secrets

object[]

Secrets to attach to the session.

Show child attributes

Response

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 browser renews short-lived bearer tokens at the widget host with RenewWidgetSession, authenticated by its existing token. Renewal preserves this bounded grant and does not extend its hard expiry.

metadata

object

required

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

Show child attributes

spec

object

required

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

Show child attributes

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

secrets

object[]

required

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.

Show child attributes

info

object

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

Show child attributes

credentials

object

Present only on creation. The same envelope is returned by RenewWidgetSession on the widget host. Omitted on reads, lists, and revocation. Existing spec.token/spec.token_expires_at and info.host remain populated on creation for v1 compatibility and agree with these credentials.

Show child attributes

Overview

Tool Sets

Tools

Tool Set Secrets

Agents

Agent Variations

Agent Schedules

Objectives

Widgets

Widget Sessions

Tenants

Memory Layers

Memory Entries

Models

Uploads

Workspaces

Workspace Secrets

Workspace Admin

Accounts

API Keys

AI Provider Keys

Webhook Events

Create a widget session

Authorizations

Path Parameters

Body

Response