How to Use HAAPI in an App Extension or App Widget#

You want an iOS App Extension (Widget, Action extension, intent) or an Android App Widget to refresh and use access tokens without forcing the user back through the full HAAPI flow. The trick: extensions and widgets cannot run the full flow (attestation APIs aren’t available; widget processes can’t host the activity), but they can refresh / revoke / use tokens that the host app already obtained.

For per-platform restriction detail, see App Extension Support (iOS Only) and App Widget Support (Android Only) . This page is the cross-platform task walkthrough.

What’s Allowed#

Prerequisites#

• A working host-app HAAPI integration that already obtains tokens.
• iOS: App Group entitlement on host app + extension target.
• Android: A storage location shared between the host process and widget process (SharedPreferences is automatically scoped to the app’s package; works for both).
• Encoded HaapiConfiguration shared between the two targets (a shared module is the simplest way).

Step-by-Step#

1. Pick shared storage#

Both platforms need somewhere both processes can read/write tokens.

struct SharedTokenStorage: Storage {
    private let defaults = UserDefaults(suiteName: "group.com.example.app")!

    func read(key: String) throws -> Data? { defaults.data(forKey: key) }
    func write(key: String, data: Data) throws { defaults.set(data, forKey: key) }
    func delete(key: String) throws { defaults.removeObject(forKey: key) }
}

val appSharedPreferences: SharedPreferences =
    getSharedPreferences("haapi_token_store", Context.MODE_PRIVATE)

fun saveToken(token: SuccessfulTokenResponse) {
    appSharedPreferences.edit(commit = true) {
        putString("ACCESS_TOKEN", token.accessToken)
        putString("REFRESH_TOKEN", token.refreshToken)
    }
}

2. Build the OAuth-only accessor in the extension/widget#

Both platforms have a dedicated builder option that skips the parts of the accessor depending on attestation / Activity — exposing only OAuthTokenManager.

let haapiAccessor = HaapiAccessorBuilder(haapiConfiguration: sharedConfiguration)
    .setHaapiAccessorOption(.oauth)
    .buildForHaapi()

// refresh the token
let tokenResponse = try await haapiAccessor.oAuthTokenManager.refreshAccessToken(
    refreshToken: cachedRefreshToken
)

GlobalScope.launch(Dispatchers.IO) {
    val accessor = HaapiAccessorFactory(haapiConfiguration).createForOAuth()
    val tokenResponse = accessor.oAuthTokenManager.refreshAccessToken(
        refreshToken = refreshToken,
        onCoroutineContext = this.coroutineContext
    )
    when (tokenResponse) {
        is SuccessfulTokenResponse -> saveToken(tokenResponse)
        is ErrorTokenResponse -> {
            // invalid_grant — clear shared storage; host app must re-authenticate
        }
    }
}

3. Handle invalid_grant by deferring to the host#

If refreshAccessToken returns an ErrorTokenResponse with error == "invalid_grant", the refresh token is dead — the SDK clears any bound DPoP keys automatically. The extension / widget cannot recover by itself; it must clear the shared token store and signal the host app to prompt re-authentication on next launch.

Verify It Works#

• Host app authenticates once and persists tokens to shared storage.
• Force-quit the host app; trigger the extension or widget.
• Confirm the extension / widget refreshes the token, persists the new one, and successfully fetches data from your resource server.

Pitfalls#

• Short lifetime, limited CPU budget. Extensions and widgets get short-lived processes. A token refresh that needs a single round trip is fine; custom retry loops or batched operations are not. On retryable errors, propagate — let the host app retry on next foreground.
• iOS App Extension can’t do attestation. Don’t try to run HaapiManager.start(...) in the extension. It’ll fail with an attestation error and confuse the user. Always use .setHaapiAccessorOption(.oauth) to expose only the refresh surface.
• Plain UserDefaults / SharedPreferences for tokens. Convenient but not encrypted at rest. For production deployments where the tokens grant access to user data, use Shared Keychain (iOS) or EncryptedSharedPreferences (Android).
• Configuration drift. Two targets, two sources of truth. Encode HaapiConfiguration in a shared module so the host and extension/widget always agree. Mismatched configurations cause refresh requests to be rejected with invalid_client.
• Android GlobalScope.launch. The upstream example uses GlobalScope.launch(Dispatchers.IO); modern Android prefers lifecycle-scoped coroutines or WorkManager. If your app already uses one of those patterns, use it here too — GlobalScope is just the upstream’s defensive choice for short-lived widget processes.