This page describes the component descriptor structure returned by the native journey. Use it to implement the visual and functional components of your native login experience.

Screens

The screen field represents the current logical step in the login or registration flow - for example, identification, password, registration. Use it to determine which screen to display and whether any special handling is needed.

The full screen state object returned by every native journey response:

📘

In minimal response mode the render field is not included in any widget, and the layout and branding top-level fields are omitted. See Minimal response mode.

Forms and widgets

This section describes the widget types returned in the forms[].widgets array. Each widget has a type and an id. The application is responsible for rendering each widget type and collecting the user's input.

Common fields

Every widget includes:

📘

Submission format

Widget id values use dot notation to represent a path into a nested object. When building the form submission body, expand dot-separated ids into nested objects rather than using them as flat keys. For example, ids address.city and address.country become { "address": { "city": "...", "country": "..." } }, not { "address.city": "...", "address.country": "..." }.

Widget types

static

Display-only text or HTML content. Does not collect user input.

{
	"type": "static",
	"id": "section-title",
	"value": "Sign in"
}

input

A single-line text input field.

{
	"type": "input",
	"id": "email",
	"label": "Email",
	"value": null,
	"readonly": false,
	"autocomplete": "username",
	"inputmode": "email",
	"validator": {
		"required": true,
		"minLength": null,
		"maxLength": null,
		"regex": null
	}
}

password

A password input field. May include a quality indicator.

{
	"type": "password",
	"id": "password",
	"label": "Enter your password",
	"qualityIndicator": false,
	"validator": null
}

passcode

A fixed-length passcode input, typically used for MFA.

{
	"type": "passcode",
	"id": "passcode",
	"label": "6-digit passcode",
	"validator": {
		"length": 6
	}
}

phone

A phone number input field.

{
	"type": "phone",
	"id": "phone",
	"label": "Telephone number",
	"value": null,
	"readonly": false,
	"validator": {
		"required": true
	}
}

date

A date input field.

{
	"type": "date",
	"id": "dob",
	"label": "Date of birth",
	"value": null,
	"readonly": false,
	"validator": null
}

checkbox

A boolean toggle field.

{
	"type": "checkbox",
	"id": "keepMeLoggedIn",
	"label": "Keep me logged in",
	"readonly": false,
	"value": false,
	"validator": {
		"required": false
	}
}

select

A single-choice selection field.

{
	"type": "select",
	"id": "country",
	"label": "Country",
	"value": null,
	"readonly": false,
	"options": [
		{ "type": "item", "value": "us", "label": "United States" },
		{ "type": "item", "value": "de", "label": "Germany" }
	],
	"validator": {
		"required": true
	}
}

multiSelect

A multi-choice selection field.

{
	"type": "multiSelect",
	"id": "interests",
	"label": "Interests",
	"value": [],
	"readonly": false,
	"options": [
		{ "type": "item", "value": "news", "label": "News" },
		{ "type": "item", "value": "sports", "label": "Sports" }
	],
	"validator": {
		"minSelectable": 1,
		"maxSelectable": 3
	}
}

submit

A form submission button or link. Submitting this widget advances the flow.

{
	"type": "submit",
	"id": "submit",
	"label": "Continue"
}

close

Signals the end of the journey and instructs the application to close or exit the login experience. No form submission is needed.

{
	"type": "close",
	"id": "close",
	"label": "Done"
}

passkeyLogin

Triggers a WebAuthn passkey assertion for login.

passkeyEnroll

Triggers a WebAuthn passkey registration (enrollment).

webauthnLogin

Triggers a WebAuthn assertion for a specific authenticator type.

webauthnEnroll

Triggers a WebAuthn registration for a specific authenticator type.

Layout

The layout object (included in full/non-minimal responses) describes how widgets from different forms should be arranged on the screen. It supports nested vertical and horizontal grouping.

type LayoutWidget = {
	type: 'vertical' | 'horizontal';
	items: Array<{ type: 'widget'; formId: string; widgetId: string } | LayoutWidget>;
};

Each leaf node references a widget by formId + widgetId. Use this to compose the visual layout rather than rendering forms sequentially.

Branding

The branding object (included in full/non-minimal responses) provides tenant-level styling data: