Token-based Setup

Token-based setup is the recommended way to initialize the SDK. Instead of exposing your API key on the client side, your back end uses the key to create an onboarding session and returns a session token to the client. The client then uses that token to initialize the SDK and start onboarding for that specific session. This approach improves security by keeping your API key on the server and reducing the risk of unauthorized API access.

Prerequisites

• A session token issued by your backend.
• The apiUrl provided by Incode.

Set up the SDK with a token

Token-based setup has three steps: initialize the SDK with an empty apiKey and your apiUrl; create a sessionConfig with your backend token; then pass that config to your chosen flow API.

1. Initialize the SDK without an API key

Pass an empty string for apiKey and provide your apiUrl to initializeSDK().

cordova.exec(
  function () {
    console.log("SDK initialized — safe to start onboarding");
    setupSessionWithToken();
  },
  function (err) {
    console.log("Init error:", err);
  },
  "Cplugin",
  "initializeSDK",
  [
    "",                              // apiKey — empty for token-based setup
    "https://your.api.url",          // apiUrl
    "true",                          // loggingEnabled
    "false",                         // testMode
    null,                            // clientExperimentId
    null,                            // e2eeUrl (optional; set if using E2EE)
    { enabled: false, forceSSLPinning: false } // sslPinningConfig
    // optional: "standard", "false", "false" — sdkMode, externalAnalyticsEnabled, externalScreenshotsEnabled
  ]
);

2. Configure the session with a token

After initialization succeeds, create a sessionConfig and pass your session token.

var sessionConfig = {
  token: "YOUR_TOKEN",
};

3. Start onboarding or set up a section-based flow

Pass the configured sessionConfig to startOnboarding(), setupOnboardingSession(), or any of the online-configured flow methods. Token-based setup works with all three Common Implementation Patterns.

// Section-based — create/resume session first
cordova.exec(
  function (data) {
    console.log("Session ready:", data.interviewId, data.token);
  },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "setupOnboardingSession",
  [sessionConfig]
);

// End-to-end — pass token in sessionConfig to startOnboarding
cordova.exec(
  function (result) { console.log("Done:", result); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "startOnboarding",
  [sessionConfig, flowConfig, recordSessionConfig]
);

// Dashboard flows — same sessionConfig
cordova.exec(..., "startFlow", [sessionConfig, "EMAIL"]);
cordova.exec(..., "startWorkflow", [sessionConfig]);

Token expiration

Tokens are long-lived, so expiration during a session is unlikely. If a token does expire mid-session, the backend returns a 401 error, which is propagated to the SDK. Tokens cannot be refreshed; the user must start a new onboarding session, which generates a new token.