Android Representations#

The Curity HAAPI Android SDK delivers every HAAPI response as a typed Kotlin value. HaapiResponse is the sealed root returned by HaapiManager.start, submitForm, and followLink; concrete subtypes — HaapiRepresentation for step-shaped responses and ProblemRepresentation for RFC 7807 errors — tell you what the server is asking the client to do.

The same model hierarchy exists on iOS and React Native — see iOS Representations and React Native Representations for the per-platform shape. This page is the Android narrative reference.

Response Hierarchy#

HaapiResponse is a sealed Kotlin interface with two sealed children:

Branch with a when expression on the response, then narrow on the concrete step or problem class.

Step Types#

HaapiRepresentation is the sealed interface for renderable steps. A parallel ClientOperationStep sealed interface captures steps that delegate to an external operation (BankID, WebAuthn, external browser, …).

Common fields#

Every step exposes these base fields:

The 14 step types#

Grouped by purpose:

Branching on the result#

import se.curity.identityserver.haapi.android.sdk.models.*
import se.curity.identityserver.haapi.android.sdk.models.actions.*

val response: HaapiResponse = haapiManager.start()

when (response) {
    is HaapiRepresentation -> handleRepresentation(response)
    is ProblemRepresentation -> handleProblem(response)
}

private fun handleRepresentation(representation: HaapiRepresentation) {
    when (representation) {
        is AuthenticatorSelectorStep -> {
            // representation.title.literal, representation.authenticators
            // Each AuthenticatorOption carries an Action.Form for selection.
        }
        is InteractiveFormStep -> {
            // representation.actions contains form actions;
            // render their fields as a Compose / View form.
        }
        is PollingStep -> {
            // representation.properties.status, representation.mainAction, representation.cancelAction
        }
        is OAuthAuthorizationResponseStep -> {
            // Flow complete — extract the authorization code.
            val code = representation.properties.code
        }
        is ClientOperationStep -> {
            // Delegate to the platform (BankID, WebAuthn, external browser, …)
        }
        else -> {
            // GenericRepresentationStep, ContinueSameStep, UserConsentStep, RedirectionStep.
        }
    }
}

Actions#

Actions represent operations the user can perform. They live under the sealed Action class:

Every action also carries:

Action.Form#

Submitting a form is the SDK’s primary write operation:

val formAction: Action.Form = …

val parameters: Map<String, Any> = mapOf(
    formAction.model.fields[0].name to "user@example.com",
    formAction.model.fields[1].name to "secret"
)

val next = haapiManager.submitForm(formAction, parameters)

submitForm’s parameters accept any JSON-serialisable value (String, Number, Boolean, nested maps, lists) for non-GET methods; GET form actions require Map<String, String>. See HAAPI Flow for the full parameter-type semantics across platforms.

The FormActionModel carries:

Action.ClientOperation#

Six sub-types of ClientOperationActionModel, each with its own fields: ExternalBrowser, BankId, Encap, WebAuthnRegistration, WebAuthnAuthentication, Generic. Each model includes continueActions and errorActions lists for post-operation flow.

Form Fields#

FormField is a sealed Kotlin class with 7 subclasses:

Common fields#

Rendering guide#

Problems#

Problem responses follow RFC 7807. Android exposes them as concrete ProblemRepresentation subclasses:

InvalidInputProblem.invalidFields is the right hook for showing field-level validation errors inline in your form.

Token Responses#

OAuthTokenManager.fetchAccessToken, refreshAccessToken, and revokeRefreshToken return a TokenResponse sealed interface. Branch its variants:

SDK-thrown errors (network, attestation, framework) come back through the coroutine’s exception channel, not as a TokenResponse variant. See OAuthTokenManager for the full lifecycle, and Error Handling for the difference between RFC-6749 OAuth errors (values) and framework errors.

Links#

Each Link carries:

Render link sets alongside the main form — typically as secondary buttons or text links.

Classify before acting#

Not every link is a HAAPI step. Call link.kind(baseUri) and act on the result rather than following every link:

when (link.kind(baseUri)) {
    LinkKind.HAAPI -> haapiManager.followLink(link)
    LinkKind.INLINE_IMAGE -> render(link.href)   // e.g. a data: QR image
    LinkKind.EXTERNAL -> startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(link.href)))
}

kind is pure and deterministic: it performs no network I/O and reads only the link plus baseUri, which is used to resolve a relative href before its scheme is examined. Media types are compared normalized — lower-cased, parameters after ; stripped. The rules are evaluated in order:

1. a type of image/* is INLINE_IMAGE;
2. a type of text/html is EXTERNAL;
3. a rel of download is EXTERNAL;
4. a blank href, or a resolved scheme other than http/https, is EXTERNAL;
5. any other declared type is EXTERNAL;
6. otherwise — including when type is absent — it is HAAPI.

Classification never decides whether the target is really your identity server; HaapiManager.followLink enforces that at follow time.