---
title: "Create a sign-in window session"
method: POST
path: "/connect/sessions"
tags: ["accounts"]
---

# Create a sign-in window session

`POST /connect/sessions`

## Request

- The document declares no server URL.
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/hevn-inc/apis/hevn-api/docs/connect/sessions/post.ts> (a function with typed inputs; its response is checked against the schema)

Issue a short-lived URL for the HEVN sign-in window. Open it in a popup from your page: `link` lets the account holder connect their account and returns a code for `POST /clients/link`, `sign` lets the holder of a connected account approve one payout that waits for their signature. The result comes back on `redirectUri` with `state`.

## Headers

- `X-Hevn-Account` string, nullable: The client account to act for, as a `cl_…` id. Omit it to act as yourself.

## Request body

- ConnectSessionRequest
  - `action` 'link' | 'sign' | 'verify', required
  - `payoutId` string, nullable: The payout the account holder approves. Required for `sign`, not accepted for `link`.
  - `clientId` string, nullable: The connected individual client whose holder verifies their identity. Required for `verify`, not accepted otherwise. The holder must sign in to this account in the window.
  - `redirectUri` string, required: Page the sign-in window returns to with the result and `state`. Its origin must be one of the allowed origins in the sign-in window settings.

## Response `201`

Successful Response

- ConnectSessionResponse
  - `url` string, required: Open this URL in the sign-in window. It works once per result and expires.
  - `state` string, required: Comes back as `state` on the redirect URI; match it before trusting the result.
  - `expiresAt` string, date-time, required: When the session URL stops working.

## Other responses

- `422`: Request validation failed

## Changes

- **2026-11-12** `299a3aa6f521`: 1 warning, 4 info
  - added the new `verification_not_applicable` enum value to the `error/code` response property for the response status `422`
  - added the new optional request property `clientId`
  - added the new `verify` enum value to the request property `action`
  - removed the `phone_required` enum value from the `error/code` response property for the response status `422`
  - …1 more
- **2026-10-23** `a02795de2d2b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hevn-inc/apis/hevn-api/changes/connect/sessions/post.md)

---

[API](https://skmtc.dev/hevn-inc/apis/hevn-api.md) - [All operations](https://skmtc.dev/hevn-inc/apis/hevn-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hevn-inc/apis/hevn-api/revisions/299a3aa6f521?raw)