---
title: "Token-Based Setup"
url: "https://developer.incode.com/sdk-reference/ios-token-based-setup/"
section: "sdk-reference"
group: "iOS SDK / iOS Getting Started"
version: "v1.1"
status: "live"
---
# Token-Based Setup

Initialize the SDK without an API key by providing only a URL to `initIncdOnboarding`, then using a session `token` to configure your onboarding session.

Token-based setup is a security measure that avoids exposing your API key in the mobile app. Instead of embedding the API key or sending it to the app, your backend uses the API key to create a session token, then sends that token to the app to start the onboarding session. This prevents attackers from extracting the API key and calling Incode APIs on your behalf.

## Prerequisites

* A session `token` issued by your backend.
* The API URL provided by Incode, ending in `/0` — the environment that does not require an API key.

## Set up the SDK with a token

Token-based setup has three steps: initialize the SDK with only a URL, configure your session with a `token`, then start onboarding or set up a section-based flow.

### 1. Initialize the SDK without an API key

Provide only the `url` to `initIncdOnboarding` and omit `apiKey`. Use the URL ending in `/0`, which specifies the environment that does not require an API key.

```swift
IncdOnboardingManager.shared.initIncdOnboarding(
    url: "https://demo-api.incodesmile.com/0"
) { success, error in
    // `success` is `true` once the SDK is ready; `error` is an `IncdInitError` on failure.
}
```

See [Installation](/sdk-reference/setup-ios/#initialize-the-sdk) for the full parameter list.

### 2. Configure the session with a token

Create the onboarding session on your backend with the `omni/start` API method, which returns a `token`. Pass that token to `IncdOnboardingSessionConfiguration` before starting the flow.

```swift
let sessionConfig = IncdOnboardingSessionConfiguration(token: "<SESSION_TOKEN>")
```

You do not need to set `interviewId` or `configurationId`. The `token` alone is enough, and all configuration set on that session is applied.

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

Pass the configured `IncdOnboardingSessionConfiguration` to `startOnboarding`, `setupOnboardingSession`, `startFlow`, or `startWorkflow`. Token-based setup works with all of the [integration patterns](/sdk-reference/ios-flow-configuration/).

Running the whole flow end to end with `startOnboarding`:

```swift
let flowConfig = IncdOnboardingFlowConfiguration()
flowConfig.addIdScan()
flowConfig.addSelfieScan()

IncdOnboardingManager.shared.startOnboarding(
    sessionConfig: sessionConfig,
    flowConfig: flowConfig,
    delegate: self
)
```

Running the flow step by step with `setupOnboardingSession` and sections:

```swift
IncdOnboardingManager.shared.setupOnboardingSession(sessionConfig: sessionConfig) { result in
    guard result.error == nil else {
        // The session could not be created. Read `result.error`.
        return
    }

    let flowConfig = IncdOnboardingFlowConfiguration()
    flowConfig.addIdScan()

    IncdOnboardingManager.shared.startOnboardingSection(
        flowConfig: flowConfig,
        sectionTag: "id",
        delegate: self
    )
}
```

## 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.