Choose Your Layer#
Each Curity Hypermedia Authentication API SDK ships three layers. They are not alternatives — they form a hierarchy. The UI Layer composes the SDK Layer, which composes the Driver Layer. Pick the highest layer that meets your needs; the lower layers are escape hatches.
Three Questions#
1. Do You Want Curity’s Prebuilt UI Screens?#
Yes (iOS or Android) → UI Layer (UIKit on iOS, UIWidget on Android).
You get themable screens for the full authentication flow (login, BankID, polling, WebAuthn, problem messages, and others). You write almost no UI code. You can theme colors, fonts, and images, and replace individual layouts via UI Extensibility. Most production iOS and Android apps start here.
You give up: full pixel-level control over the screens. Curity controls the navigation between authentication steps.
React Native: there is no UI Layer for React Native. RN apps always start at the SDK Layer (question 2 below).
No → continue to question 2.
2. Do You Want Curity to Handle the HAAPI Protocol Mechanics While You Build Your Own UI?#
Yes → SDK Layer (HaapiManager, OAuthTokenManager).
You get structured stepping through the authentication flow — start → submit → followLink — with each step delivered as a typed model (InteractiveFormStep, AuthenticatorSelectorStep, PollingStep, and others) that your UI renders. The SDK manages attestation, Dynamic Client Registration fallback, DPoP, token refresh, and error categorization for you. React Native apps almost always start here — RN’s only public surface maps to this layer.
You give up: control over the flow mechanics. You cannot reorder steps or skip the protocol’s structure.
No → continue to question 3.
3. Do You Need to Drive HAAPI Requests Over Your Own HTTP Client?#
Yes → Driver Layer (HaapiTokenManager, direct DPoP access).
You get the building blocks: a HaapiTokenManager that hands you DPoP access tokens and proof tokens for any URL and method combination. You wire those tokens into your own HTTP requests. You handle session identifiers, nonce rotation hints (or use the framework-managed nonce), and error responses yourself.
You give up: nearly all of the SDK’s convenience. This layer is an escape hatch — most apps never need it.
Not Sure → if you are not sure, you do not need this layer. Default to the SDK Layer or the UI Layer.
What Each Layer Gives You#
| UI Layer | SDK Layer | Driver Layer | |
|---|---|---|---|
| Prebuilt UI screens | ✅ | ❌ | ❌ |
| Structured flow stepping | ✅ | ✅ | ❌ |
| OAuth token management (refresh, revoke) | ✅ | ✅ | ❌ |
| Attestation and DCR fallback | ✅ | ✅ | partial (manual) |
| DPoP token binding | ✅ | ✅ | ✅ (manual) |
| You write the UI | minimal (theming) | ✅ | ✅ |
| You write the HTTP transport | ❌ | ❌ | ✅ |
| iOS available | UIKit | ✅ | ✅ |
| Android available | UIWidget | ✅ | ✅ |
| React Native available | ❌ (use SDK Layer) | ✅ | ❌ |
Where to Next#
Pick a starting page based on your answers above:
- UI Layer (iOS and Android) → iOS UIKit · Android UIWidget · Theming
- SDK Layer (all platforms) → iOS SDK · Android SDK · React Native SDK · HAAPI Flow
- Driver Layer (iOS and Android) → iOS Driver · Android Driver · HaapiTokenManager · Attestation
If you would rather see a working integration before committing, jump to the per-platform quickstarts: iOS · Android · React Native .