# 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](https://developer.incode.com/docs/configuration-api-keys-tab). 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`.

```swift
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.

```swift
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](https://developer.incode.com/docs/ios-api-reference) or contact Incode support.

<br />