# Create a Connect session

One call of the distributor API, read from the interface description Yutai publishes. Every sample answer on this page is simulated: no real holder's data stands behind it. The formats every value travels in are the [identifiers page](/docs/identifiers)'s.

## The call

POST `/v1/connect/sessions` Callable today

The key presents the `connect.write` scope.

## The body

`externalRef`: Required. Your own opaque id for the person the session is for. It is never an email address or a phone number.

`returnUrl`: Required. Where the hosted page sends the person back: an https address on your allowed origins, or your app's own scheme when your profile lists it.

`context`: Optional. The brand the person came from, named by exactly one of an ISIN or a company id. Leave it out when there is none.

`locale`: Optional. The language the hosted page speaks, as a language tag such as en-GB.

`mode`: Optional. How the result returns: redirect brings the browser back, popup answers the page that opened it, and app uses the phone's in-app browser.

`view`: Optional. What the hosted page shows: consent for a new link, or purchases to read and manage a link that already stands.

`wallets`: Optional. The holder's wallet addresses to read on chain, each once, at most 20 in one session.

## What it answers

The session's id, the hosted page's address the distributor's app opens, and the instant its one-time token expires, 900 seconds after the call. The address carries the token once; the store keeps only its digest.

- `id` Required. A string.
- `connectUrl` Required. A string.
- `expiresAt` Required. An instant in the ISO 8601 form.

## The errors

Every refused call answers one object with one field, message: the plain sentence that says what did not happen. The sentence carries 1 to 512 characters, so a refusal never carries an id, a code or an exception's text.

| Status | What it answers |

| --- | --- |

| 400 | The request body could not be read. |

| 401 | The key is missing, malformed, unknown, revoked or expired. |

| 403 | The key does not carry the scope, or the return address is not one the distributor's profile allows. The call is also refused with 403, nothing read, when the distributor is paused, suspended or closed, when the key is paused, or when the key presents from an origin it does not allow. |

| 429 | The key made too many calls this minute. The Retry-After header names the seconds until the next window opens. Nothing was read. |

| 500 | The read failed inside Yutai. Nothing was changed. |