Start or resume a LoginUI runtime Flow interaction.

POST

/api/v1/login/interactions/start

Code sample: Shell / cURL

curl --request POST \
  --url https://auth.example.com/api/v1/login/interactions/start \
  --header 'Content-Type: application/json' \
  --data '{ "flow_kind": "login", "target_type": "tenant", "target_id": "example", "client_id": "example", "saml_sp_id": "example", "scope": [ "example" ], "requested_scope": [ "example" ], "locale": "example", "requested_locale": "example", "authorization_challenge_id": "example", "saml_request_id": "example", "saml_sp_entity_id": "example", "return_to": "example", "resume_interaction_id": "example", "contract_hash": "example", "signature": "example" }'

Creates a LoginUI runtime Flow interaction for login, registration, approve, or account flows, or resumes an existing interaction when a signed resume request is supplied. The endpoint is feature-flagged and returns a signed runtime contract without AdminUI editor state.

Request Body ^required

Media type application/json

object

flow_kind

string

Example

login

target_type

string

Allowed values: tenant oidc_client saml_sp

target_id

string | null

client_id

string

saml_sp_id

string

scope

One of:

string

string

Array<string>

Array<string>

requested_scope

One of:

string

string

Array<string>

Array<string>

locale

Preferred language for runtime Flow content.

string

requested_locale

Preferred language for runtime Flow content.

string

authorization_challenge_id

OIDC authorization login challenge to continue when the Flow completes without a direct authentication endpoint returning the continuation URL.

string

saml_request_id

SAML IdP request identifier to continue after the Flow completes.

string

saml_sp_entity_id

SAML service provider entity ID for Flow protocol continuation.

string

return_to

LoginUI return mode associated with the protocol request.

string

resume_interaction_id

string

contract_hash

string

signature

string

key

additional properties

Responses

200

Runtime interaction state and signed contract.

Media type application/json

object

schema_version

required

string

interaction

required

object

key

additional properties

assignment

object

key

additional properties

contract

required

object

key

additional properties

contract_hash

required

string

signature

required

string

expires_in

required

integer

resumed

required

boolean

Example ^generated

{
  "schema_version": "example",
  "interaction": {
    "additionalProperty": "example"
  },
  "assignment": {
    "additionalProperty": "example"
  },
  "contract": {
    "additionalProperty": "example"
  },
  "contract_hash": "example",
  "signature": "example",
  "expires_in": 1,
  "resumed": true
}

400

Error response.

Media type application/json

object

error

string

error_description

string

message

string

webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object

unknown_credential

boolean

key

additional properties

Example ^generated

{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}

403

Error response.

Media type application/json

object

error

string

error_description

string

message

string

webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object

unknown_credential

boolean

key

additional properties

Example ^generated

{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}

404

Error response.

Media type application/json

object

error

string

error_description

string

message

string

webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object

unknown_credential

boolean

key

additional properties

Example ^generated

{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}

409

Error response.

Media type application/json

object

error

string

error_description

string

message

string

webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object

unknown_credential

boolean

key

additional properties

Example ^generated

{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}

500

Error response.

Media type application/json

object

error

string

error_description

string

message

string

webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object

unknown_credential

boolean

key

additional properties

Example ^generated

{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}