---
title: "Bootstrap widget visitor"
method: POST
path: "/v2/widgets/{alias_key}/bootstrap"
tags: ["Widgets"]
---

# Bootstrap widget visitor

`POST /v2/widgets/{alias_key}/bootstrap`

Mints a signed anonymous visitor id and returns it with the widget's presentation configuration.
No credential is required.

The client presents the minted id as `X-Visitor-Id` on `/v2/agent_aliases/{alias_key}/end_user_sessions` requests, using the `alias_key` returned here; the widget connector the id was minted through travels inside it.

Returns `404` if the alias does not front a widget connector, or that connector is disabled, does not have `public_access` enabled, or belongs to a disabled customer.

The visitor id never expires.
Store it durably; a repeat call mints a fresh identity that owns none of the previous identity's sessions.

## Path parameters

- `alias_key` string, required — The platform-generated key of the alias fronting a widget connector, as reported in the connector's `alias_key` and `bootstrap_path`. Always `als_`-prefixed; the prefix is reserved, so no operator-chosen alias ever matches it.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Response `200`

A minted visitor identity and the widget's presentation configuration.

- BootstrapWidgetResponse — The configuration a widget client needs to render and to open a session, and — for a widget that admits anonymous visitors — the anonymous identity to open one with. Session attributes such as idle lifetime are reported on the session object returned by the end-user session create endpoint.
  - `visitor_id` string — The anonymous identity minted for this visitor. Present only when the widget admits anonymous visitors; a sign-in-only widget returns no `visitor_id`, and its callers open a session with a customer-IdP token instead. Presented as the `X-Visitor-Id` header on every end-user session request. Store it durably on the client; it never expires, and it is the only proof of ownership of the sessions it creates.
  - `alias_key` string, required — The unique key that identifies an alias. Alias keys are independent of agent keys. The same string can exist as both an alias key and an agent key in the same customer account. Calls to `/v2/agent_aliases/{key}/...` target the alias. Calls to `/v2/agents/{key}/...` target the agent.
  - `presentation` WidgetPresentation, required — The presentation configuration the widget client renders — branding, palette, welcome content, suggested prompts. Free-form apart from the required `version`; the platform stores it verbatim, serves it back uninterpreted, and caps its total size. Null-valued keys are accepted but are omitted from responses. Served to anonymous visitors by the unauthenticated widget bootstrap endpoint, so widget clients must treat every value as untrusted data. Schema validation of the payload lands with the first Altera release; `version` is what lets clients render older payloads once the shape evolves.
    - `version` string, required — The version of the presentation payload's shape, chosen by the writer and echoed verbatim on read. Until the first Altera release the only accepted value is `beta`, marking the payload as free-form; schema-validated numbered versions arrive with that release.
  - `end_user_sign_in` WidgetSignIn — Enables the widget's sign-in affordance and names the identity provider it authenticates users against. The host page supplies a token minted by the referenced trusted token issuer, and the widget presents it as the bearer credential on end-user session requests. The platform verifies the token by its `iss` claim against the globally-unique issuer registration — never against this connector — so the token stands on its own: it signs the caller in as an end user across the customer's aliases, not this widget's alone. The platform accepts the token when its signature verifies against the issuer's JWKS and it carries an `email` claim. The referenced registration must exist, or the connector write is rejected with `400`.
    - `trusted_token_issuer_id` string, required — The unique identifier of a trusted token issuer.

## Other responses

- `404` — The alias does not front a widget connector, or that connector is disabled, does not admit anonymous visitors, or belongs to a disabled customer.
- `429` — The caller's network address exceeded the per-address minting rate. Try again shortly.

---

[API](https://skmtc.dev/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/abd45fb0c974/schema)