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
- The application initiates an OAuth 2.0 PKCE authorization request via the SDK.
- 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.
- The SDK's renderer reads the screen state and calls the application's registered widget components to render the current form.
- The user fills in the form and submits it. The renderer passes the data to the backend, which returns the next screen state.
- Steps 3–4 repeat until the screen state contains a
finalizeUrl. - 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
| Concept | Description |
|---|---|
| Screen | The current state of the journey. Identifies which step the user is on (for example,identification, registration). |
| Form | A collection of widgets to be filled in and submitted by the user. A screen can contain one or more forms. |
| Widget | An individual UI element within a form (for example, text input, password field, submit button). |
| finalizeUrl | When present in the screen state, the journey is complete. The SDK uses this URL to finalize the OAuth flow and obtain tokens. |
| hostedUrl | A 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
| Field | Type | Description |
|---|---|---|
screen | string | Identifier of the current journey step (for example, identification, registration). |
forms | array | List of Form objects, each containing a widgets array. |
layout | object | Layout descriptor defining the visual arrangement of widgets across forms. |
messages | object | Error and informational messages for the current step, including a global message. |
hostedUrl | string | Fallback URL to the hosted login page, if the screen cannot be rendered natively. |
finalizeUrl | string | Present 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.
| Platform | SDK |
|---|---|
| Web | JavaScript SDK |
| Android | Android Native SDK (Kotlin) |
| Android | Android Native SDK (Java) |
| iOS | iOS Native SDK |
| React Native | React Native SDK |
| Flutter | Flutter SDK |
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.
| Value | Use case |
|---|---|
web | Full response (SDK-based renderer on web) |
web-minimal | Minimal response (headless renderer on web) |
ios-minimal | Minimal response (headless renderer on iOS) |
android-minimal | Minimal response (headless renderer on Android) |
The following fields are omitted in minimal response mode:
| Field | Description |
|---|---|
layout | Visual arrangement descriptor for widgets across forms. |
branding | Logo, brand name, copyright, and policy links from the server. |
forms[].widgets[].render | Per-widget rendering hints (display type, colors, variant, etc.). |
