API Key Rotation

API keys used to initialize the iOS 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.

The API key authenticates the SDK during initIncdOnboarding.
A session token authenticates a single verification session. Your backend creates the session with Incode and passes the token to the app, which supplies it through IncdOnboardingSessionConfiguration(token:). Alternatively, a configurationId can be used.

Rotate Keys

When an API key is revoked from Dashboard, every onboarding session using that key is aborted. The SDK reports the revocation through the onError(_ error: IncdFlowError) method on your 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, API key revocation surfaces as IncdFlowError.error(IncdError.apiKeyRevoked(key:)). The revoked key is delivered as the associated key value. There's no separate IncdFlowError.apiKeyRevoked case to match on directly; instead, match IncdFlowError.error and check whether the wrapped IncdError is .apiKeyRevoked.

func onError(_ error: IncdFlowError) {
    if case let .error(.apiKeyRevoked(key)) = error { // associated value is the revoked API key
        // Your logic for the rotation of the key
    }
}

Reinitialize with the New Key

When you have a new API key, reinitialize the SDK by calling initIncdOnboarding(...) on IncdOnboardingManager.shared. Pass the new key as the apiKey argument in place of the original and apply any optional configuration exactly as you did on first initialization.

IncdOnboardingManager.shared.initIncdOnboarding(url: url, apiKey: newApiKey) { (success: Bool?, error: IncdInitError?) in
    // SDK has been reinitialized successfully when success == true
}

Resume or Restart Onboarding

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

For help, see API Reference or contact Incode support.