Skip to content
YutaiDocs
GET /v1/statusGet API key

API reference / API reference

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's.

View as .md

The call

POST/v1/connect/sessionsCallable 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.

The errors the call for POST /v1/connect/sessions answers
StatusWhat it answers
400The request body could not be read.
401The key is missing, malformed, unknown, revoked or expired.
403The 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.
429The key made too many calls this minute. The Retry-After header names the seconds until the next window opens. Nothing was read.
500The read failed inside Yutai. Nothing was changed.