API Key Rotation

API keys used to initialize the Android SDK can be rotated at any time for security reasons. This page shows how to detect a revoked key during an onboarding session, reinitialize the SDK with the replacement key, and resume onboarding so the user can continue.

You can revoke keys and generate new ones from Dashboard. The SDK does not rotate keys itself; it reacts to a key being revoked.

Rotate Keys

When an API key is revoked from Dashboard, every onboarding session using that key is aborted. The SDK reports the revocation through your error callback:

• Android: onError(Throwable) on IncodeWelcome.OnboardingListener()
• iOS: onError(_ error: IncdFlowError) on IncdOnboardingDelegate

That callback is where you detect the revocation and replace the key. The rotation flow has three steps, explained below. Complete them in order.

Detect the Revoked Key

In your error handler, check for the rotation error type. On Android, the error is an ApiKeyRotationException.

override fun onError(error: Throwable) {
    if (error is ApiKeyRotationException) {
        // Your logic for the rotation of the key
    }
}

@Override
public void onError(@NonNull Throwable error) {
    if (error instanceof ApiKeyRotationException) {
        // Your logic for the rotation of the key
    }
}

Reinitialize with the New Key

When you have a new API key, reinitialize the SDK with it. Pass the new key in place of the original and apply any optional configuration exactly as you did on first initialization.

IncodeWelcome.Builder(application, apiUrl, apiKeyRotatedIn)
    ... // optional configuration
    .build()

// SDK has been reinitialized successfully

new IncodeWelcome.Builder(getApplication(), apiUrl, apiKeyRotatedIn)
    ... // optional configuration
    .build();

// SDK has been reinitialized successfully

IncdOnboardingManager.shared.initIncdOnboarding(url: url, apiKey: newApiKey) { (success, _) in
    // SDK has been reinitialized successfully
}

Resume or Restart Onboarding

After the SDK reinitializes, you can resume the old session or start a new onboarding session.

For help, see API Reference or contact Incode support.