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

Initialize the Android SDK without an API key by providing only an `apiUrl` to `IncodeWelcome.Builder`, 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 `apiUrl` provided by Incode.

## Set up the SDK with a token

Token-based setup has three steps: initialize the SDK with only an `apiUrl`, configure the 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 `apiUrl` to `IncodeWelcome.Builder`. Omit the API key.

```kotlin
IncodeWelcome.Builder(application, "https://your.api.url")
    // optional configuration
    .build()
```
```java
new IncodeWelcome.Builder(application, "https://your.api.url")
    // optional configuration
    .build();
```

If your `apiUrl` ends with `/0`, a token is mandatory: the SDK throws `ExternalTokenRequiredException` when the token is missing. The same applies to the E2EE URL when [End-to-End Encryption](/sdk-reference/android-e2ee/) is enabled.

### 2. Configure the session with a token

After initialization succeeds, create a `SessionConfig` and pass your session `token` to `setExternalToken`.

```kotlin
val sessionConfig = SessionConfig.Builder()
    .setExternalToken("YOUR_TOKEN")
    .build()
```
```java
SessionConfig sessionConfig = new SessionConfig.Builder()
    .setExternalToken("YOUR_TOKEN")
    .build();
```

### 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](/sdk-reference/android-common-implementation-patterns/).

```kotlin
// Section-based - create or resume the session first
IncodeWelcome.getInstance().setupOnboardingSession(sessionConfig, onboardingSessionListener)

// End-to-end - pass the token in sessionConfig to startOnboarding
IncodeWelcome.getInstance().startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener)

// Dashboard flows - same sessionConfig
IncodeWelcome.getInstance().startFlow(activityContext, sessionConfig, onboardingListener)
IncodeWelcome.getInstance().startWorkflow(activityContext, sessionConfig, onboardingListener)
```
```java
// Section-based - create or resume the session first
IncodeWelcome.getInstance().setupOnboardingSession(sessionConfig, onboardingSessionListener);

// End-to-end - pass the token in sessionConfig to startOnboarding
IncodeWelcome.getInstance().startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener);

// Dashboard flows - same sessionConfig
IncodeWelcome.getInstance().startFlow(activityContext, sessionConfig, onboardingListener);
IncodeWelcome.getInstance().startWorkflow(activityContext, sessionConfig, onboardingListener);
```

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