Driver Layer Overview#

The Driver Layer is the lowest user-facing layer of the Curity HAAPI client stack. It is built around two primitives — HaapiTokenManager, which mints DPoP-bound access tokens, and an HTTP convenience that wraps those tokens into requests. Everything the SDK Layer and the UI Layer do is composed from this building block.

Most apps do not work at the Driver Layer. The SDK Layer wraps it in a structured flow with typed models and error mapping; the UI Layer wraps that in prebuilt themable screens. Choose the Driver Layer only when neither higher layer fits.

When to Choose This Layer#

• Your app already has a heavily customized HTTP transport (custom interceptors, mTLS, proxy chains, alternative HTTP clients) and you need to integrate HAAPI into it directly.
• You are embedding HAAPI into a larger networking stack that defines its own request lifecycle.
• You want full manual control over session-identifier handling, retries, and request composition.

If none of these apply, drop back to the SDK Layer — it handles attestation, DCR fallback, DPoP, token refresh, and error categorization for you.

What You Give Up#

When you drop to the Driver Layer, you take on responsibilities the higher layers handle automatically:

• Session identifier handling. The HAAPI flow uses a Session-Id header to thread state across requests. You read it from Set-Session-Id response headers and resend it on subsequent requests yourself.
• Flow stepping. There is no start → submit → followLink state machine — you walk the hypermedia responses by hand.
• Error mapping. Errors come back as raw responses; you classify them into retryable, unrecoverable, and OAuth-protocol categories yourself. See Error Handling .

DPoP nonce rotation is no longer one of these — the framework manages the nonce lifecycle internally even at the Driver Layer. See Upgrade — DPoP Nonce Auto-Management .

Topic Pages#

Configuration knobs, primitives, and operational concerns are documented on shared topic pages with iOS and Android code shown side-by-side in <Tabs>:

• HaapiTokenManager — construction, direct token retrieval, session-identifier handling, lifecycle
• Attestation (Driver Layer) — per-platform attestation mechanisms, custom policies, DCR fallback
• Token Binding — DPoP-bound authorization codes and refresh tokens
• Risk Assessment — device-context collection for BankID and similar
• Client Authentication — Secret, MTLS, Signed JWT
• Error Handling — retryable, unrecoverable, and OAuth-protocol categories
• Logging — HaapiLogger configuration

Platform Landing Pages#

Each platform’s slim landing carries the install snippet, a pointer to the auto-generated API reference, and a list of the topic pages above:

The Android landing also references HTTP Integration (Android Only) for HttpURLConnectionProvider and cookie-management specifics.