Native journey

A native journey is the integration mode where the application renders the authentication UI using its own components. Each SDK provides a built-in renderer that drives the flow and calls the application's registered widget components to render each step. The application supplies its own implementation of each widget type, which gives full control over the look, feel, and behavior of the authentication screens.

This mode is available on all platforms.

📘

Why use an SDK instead of calling the Journey Flow API directly?

Strivacity SDKs handle flow orchestration, token lifecycle, PKCE, redirects, fallbacks, and widget semantics so your application stays decoupled from backend flow logic. If policies or steps change (for example, a new MFA requirement is added), the app keeps working without any code changes (assuming the rendering is based on the returned schema and the fallback option is in use). SDKs are the secure, maintainable, and future-proof integration path.

If you need full control over rendering, you can implement your own renderer while still using the SDK for session and flow management. See Headless renderer below.

How it works

  1. The application initiates an OAuth 2.0 PKCE authorization request via the SDK.
  2. A session is started or resumed. The SDK acquires and manages a session token for the duration of the flow. The backend returns a screen state object describing the current step of the journey.
  3. The SDK's renderer reads the screen state and calls the application's registered widget components to render the current form.
  4. The user fills in the form and submits it. The renderer passes the data to the backend, which returns the next screen state.
  5. Steps 3–4 repeat until the screen state contains a finalizeUrl.
  6. The application completes the OAuth flow via the SDK using the finalizeUrl to receive tokens.

Required client type

A native journey requires the client type OIDC (using the Journey Flow API) registered under your application in the Strivacity Admin Console.

After creating the client, configure the Entry URL and Web configuration, and platform-specific passkey origins in the SDK configuration tab. See Client configuration.

Key concepts

ConceptDescription
ScreenThe current state of the journey. Identifies which step the user is on (for example,identification, registration).
FormA collection of widgets to be filled in and submitted by the user. A screen can contain one or more forms.
WidgetAn individual UI element within a form (for example, text input, password field, submit button).
finalizeUrlWhen present in the screen state, the journey is complete. The SDK uses this URL to finalize the OAuth flow and obtain tokens.
hostedUrlA fallback URL to the hosted login page. Use this to fall back to a hosted journey if a screen cannot be rendered natively.

Screen state object

FieldTypeDescription
screenstringIdentifier of the current journey step (for example, identification, registration).
formsarrayList of Form objects, each containing a widgets array.
layoutobjectLayout descriptor defining the visual arrangement of widgets across forms.
messagesobjectError and informational messages for the current step, including a global message.
hostedUrlstringFallback URL to the hosted login page, if the screen cannot be rendered natively.
finalizeUrlstringPresent when the journey is complete. Pass to finalizeSession().

For the full widget type reference, see Rendering reference.

SDK support

Native journeys are supported by all Strivacity SDKs across web and mobile platforms.

Headless renderer

Instead of using the SDK's built-in renderer, an application can implement its own rendering logic directly. In this model, the application reads the screen value from the screen state and maps it to its own pre-built UI components. Each component is responsible for collecting input and calling the appropriate SDK method (for example, handler.submitForm(formId, data)) to advance the flow. The SDK's widget registration and renderer loop are not used.

This approach gives the application complete control over the UI and is well-suited for cases where the authentication screens are fully static and pre-designed.

When an error occurs (for example, because the server returns a screen that the application does not handle), the application should redirect the user to the hosted login page using state.hostedUrl.

Minimal response mode

When implementing a headless renderer, the rendering hints returned by the server are generally not needed. These fields can be excluded by passing an sdk parameter in the initial authorization request. This reduces response size and simplifies the data the application needs to handle.

ValueUse case
webFull response (SDK-based renderer on web)
web-minimalMinimal response (headless renderer on web)
ios-minimalMinimal response (headless renderer on iOS)
android-minimalMinimal response (headless renderer on Android)

The following fields are omitted in minimal response mode:

FieldDescription
layoutVisual arrangement descriptor for widgets across forms.
brandingLogo, brand name, copyright, and policy links from the server.
forms[].widgets[].renderPer-widget rendering hints (display type, colors, variant, etc.).