Registration flow

Registration proves control of an email address, then binds a device key to the identity. It has two branches that share a start:

• Existing identity — the user is already known to the directory. Verify the emailed PIN and a device key is minted. No face capture in this branch.
• Self-signup — the identity is new and the application allows signup. After the PIN, the SDK collects profile attributes and a consent acknowledgement, then captures a face to mint a fresh face token.

Which branch you land in is decided by the server, not by your app. Observe the state stream and render whatever it asks for.

Starting the flow

let flow = try authn.startRegistrationFlow(
    email: "alice@example.com",
    clientId: "your-client-id",
    sessionId: nil
)

Task {
    for await state in flow.stateStream() {
        handle(state)
    }
}

val flow = withContext(Dispatchers.IO) {
    authn.startRegistrationFlow(
        email = "alice@example.com",
        clientId = "your-client-id",
        sessionId = null,
    )
}

lifecycleScope.launch {
    flow.state.collect { state -> handle(state) }
}

sessionId matters for the self-signup branch: when present, the SDK sends it on completion so the server finishes the OAuth session in the same call, and the user is not asked for a second face scan.

This method throws — see AuthnRuntimeError.

The state machine

States and their payloads

Step 1 — the email PIN

flow.submitPin(pin: entered)
flow.resendPin()

flow.submitPin(entered)
flow.resendPin()

The awaitingPin payload gives you everything the screen needs:

• attemptsLeft — remaining tries. Exhausting them terminates with failed(reason: .pinAttemptsExhausted).
• pinExpiresInSeconds — for a countdown. Expiry terminates with failed(reason: .pinExpired).
• cooldownUntil — Unix timestamp until which resendPin() is rate-limited. Disable the resend button until then.
• codeDispatched — whether an email was actually sent on this transition.

Step 2 — the self-signup branch

If the server flags signup, you get collectingAttributes with the directory's enabled attribute schema. Render one typed input per entry, in ordering order.

Each SignupAttribute carries:

name is included in the schema; email is not — it is already known.

The consent gate

termsUrl and privacyUrl are the effective Terms-of-Use and Privacy-Policy URLs, resolved server-side from a per-app override or the deployment default.

nil means the server predates this feature; skip the consent gate in that case.

Submitting the form

flow.submitSignupAttributes(
    values: ["name": "Alice Smith", "phone_number": "+15551234567"],
    address: ["street_address": "1 Main St", "locality": "Springfield"],
    consentAccepted: true
)

flow.submitSignupAttributes(
    mapOf("name" to "Alice Smith", "phone_number" to "+15551234567"),
    mapOf("street_address" to "1 Main St", "locality" to "Springfield"),
    true,
)

values is keyed by attribute key, with scalars as strings. address carries the structured OIDC address sub-fields separately when that attribute was filled; pass nil if not. The SDK extracts name for its dedicated wire field and forwards the rest.

Handling rejection

The server validates values the device can't check locally — most commonly a coupon code. On rejection the flow re-enters collectingAttributes with:

• rejected — a SignupAttributeRejection. Its key names the offending field, or is nil for a form-level error such as a network blip; message is the server's reason. Show it inline and re-enable the form.
• priorValues / priorAddress — what the user already typed. Re-populate the form from these so nothing has to be retyped. Both are empty/nil on first entry.

Step 3 — face capture (self-signup only)

Same driver pattern as login:

let driver = flow.faceCaptureDriver()

SenseCryptFaceScanView(driver: driver) { outcome in
    // CaptureOutcome
}

val driver = flow.faceCaptureDriver()
// Observe driver.state and submit via driver.submitFaceCapture(handle).

Step 4 — completion

On success you get succeeded(key:) carrying the minted Key. The device can now approve sign-ins.

postingResultFailed(reason:) works exactly as in login: not terminal, call retryPostResult() to re-send the cached signup proof. No face re-capture, no device-key re-mint. Gate the retry CTA on observing that state.

flow.retryPostResult()

// Retry the signup completion through the capture driver.
driver.retry()

Registration-specific failure reasons

Beyond the common reasons, these appear mainly here:

Other enrollment paths

Registration through the SDK is one of three ways a user gets enrolled. The other two happen outside your app:

• Admin provisioning — an operator creates the user in the console, optionally from a photo.
• Directory provisioning (SCIM) — your IdP creates a pending shell that the user claims on first use. See SCIM.

In every path, control of the email address is proven before a device key is bound.

Related

• Login — approving sign-ins once enrolled.
• Key management — rotating and revoking device keys.
• Errors — the complete failure surface.
• Reference — Key, SignupAttribute, and the enums.