---
title: "Generate Widget Session"
method: POST
path: "/session"
tags: ["terra"]
---

# Generate Widget Session

`POST /session`

Generate a Terra widget session for user authentication.

The User row is not required (and not created) at this point — the
Terra ``auth`` webhook handler creates it once the user actually
completes the provider connection.

We pass a **fresh, never-reused** ``reference_id`` (not the Firebase
UID) so Terra never sees the same reference twice across reinstalls —
that's what stops the duplicate-account / orphaned-data bleeding
(#979, #1094): no ambiguous state, ``user_reauth`` never fires. The
Firebase UID and the device timezone (from the ``X-Device-Timezone``
header, PR #529) are persisted on a ``TerraSession`` row keyed by the
widget session id Terra returns. The ``auth`` webhook reads the row by
``widget_session_id`` to recover the identity and canonicalize the
reference to the imperfect-api user id.

## Headers

- `x-device-timezone` string, nullable

## Request body

- WidgetSessionRequest — Request schema for generating a Terra widget session.
  - `reference_id` string, nullable
  - `language` string
  - `auth_success_redirect_url` string, required
  - `auth_failure_redirect_url` string, required

## Response `200`

Successful Response

- object

## Other responses

- `422` — Validation Error

---

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