Skip to main content
GET
JavaScript
The audit view of who is holding a live credential. Each row carries the session’s spec (minus the token), its state, and (with includeInfo) the widget, agent, tenant, subject, and activity counters in info.

Filtering

widgetId, tenantId, and subjectId each accept the canonical id form or external_id:<value>. One catch on subjects: a subject’s external ID is only unique within its tenant, so the external_id: form of subjectId requires tenantId too. state narrows to one lifecycle state:

What a row never shows

The bearer token. It exists in exactly one response, the create call, and secrets come back name-only. A leaked list response is annoying, not a credential spill.

Create a widget session

The mint, and everything a session carries.

Revoke a widget session

End any row in this list, now.

List tenants

The tenants these sessions asserted into existence.

Get a widget session

One session, in full.

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"

Query Parameters

limit
integer<int32>

Maximum number of results to return.

cursor
string

Pagination cursor from previous response.

widgetId
string

Filter to sessions on a specific widget. Accepts the canonical wgt_… form or the external_id:<value> form.

tenantId
string

Filter to sessions belonging to a tenant. Accepts the canonical tenant_… form or the external_id:<value> form.

subjectId
string

Filter to sessions asserted for a subject. Accepts the canonical subj_… form or the external_id:<value> form; the external_id form is scoped within a tenant and requires tenant_id to also be set.

state
enum<string>

Filter by state.

Available options:
STATE_UNSPECIFIED,
STATE_ACTIVE,
STATE_EXPIRED,
STATE_REVOKED,
STATE_EXHAUSTED
labels
string

Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).

sortOrder
string

Sort order for results (asc or desc by creation time).

includeInfo
boolean

When true, the info field on each returned session is populated. Requests with this flag count more against your rate limit.

Response

OK

List widget sessions response.

items
object[]
pagination
object

Page carries cursor-based pagination state. There is no total: the cursor walks the result set without ever counting it, and a count would cost a second query on every list.