Registration flow

Registration proves control of an email address, then binds a device key, generated in the phone's secure hardware, 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 AuthnInitError (Internal) when the flow cannot be constructed — see Errors.

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 completion — the signup proof, or on the device-add branch the /register/complete request. No face re-capture, no device-key re-mint, no second PIN. The one field a retry refreshes is the Android Play Integrity token the completion carries for enrolment-time attestation, minted again over the same challenge because the server accepts a token for five minutes. Only a lost answer, a 5xx or a 429 parks here; a refusal is the server's verdict on that request and ends in failed. A lost answer (no answer, a reset, a read timeout) is re-sent once by the SDK itself first, after a short pause — the server re-serves the same completion with its original response and writes nothing — so postingResultFailed after a lost answer means two lost answers in a row; a 5xx or a 429 parks here at once. Gate the retry CTA on observing that state.

flow.retryPostResult()

// Signup branch: retry through the capture driver...
driver.retry()
// ...or, on either branch, directly on the flow.
flow.retryPostResult()

One device per user

A tenant may allow each user one device (the console's Issuer page, or one_device_per_user on PATCH /v1/admin/issuer). Under such a tenant, enrolling a further phone signs the user's other phones out, and the user must agree to that on the new phone first.

The SDK handles the server side of it. On /register/verify it names the phone it is enrolling, and when the answer lists the user's other phone(s) the flow pauses in awaitingDeviceReplacementConfirm(otherDevices:) before the device key is minted, so nothing has been written yet. Each OtherDevice carries deviceName, os, osVersion (any of them nil for a phone enrolled before the server recorded them) and lastUsedAt (RFC 3339). Show the user which device will go and ask:

case let .awaitingDeviceReplacementConfirm(otherDevices):
    // "Adding this device signs out <name>, last used <when>. Continue?"
    if userAgreed {
        flow.confirmDeviceReplacement()
    } else {
        flow.cancel()
    }

is RegistrationState.AwaitingDeviceReplacementConfirm -> {
    // "Adding this device signs out <name>, last used <when>. Continue?"
    if (userAgreed) flow.confirmDeviceReplacement() else flow.cancel()
}

confirmDeviceReplacement() sends the completion with the user's confirmation; the server revokes their keys on every other phone in the same transaction as the new key, and the flow continues to succeeded. cancel() leaves every phone as it was; the registration token lapses unspent. The same state can also arrive from the completion itself, when the server could not see the other phone at verify time (the setting was turned on, or another phone was enrolled, in between): the SDK holds the exact request it sent and re-sends it on confirmation.

A reinstalled phone counts as a further device: the SDK mints a fresh device id after it wipes its last key, so the user's own earlier copy is listed and they are asked to sign it out. Confirming is harmless; that copy no longer holds a key.

The other phone learns on its next request, sync or rotation that its key is gone because the account moved: the SDK reports deviceKeyReplaced rather than deviceKeyRevoked, RevokedKeyNotice.replaced on a rotation, and BrandingSyncSummary.replacedKeys on a sync. Say so, and do not offer to add the account there again by default: that would sign the new phone out in turn.

Android 9–13: the system-passkey branch

Android 9 to 13 cannot host a third-party passkey provider, so on those versions the passkey is kept in Google Password Manager. Start the flow with systemPasskeyMode = true (Kotlin only) and the SDK mints no local passkey. Instead, after the device key is generated, it emits awaitingSystemPasskey(requestJson); run an in-app Credential Manager createCredential() with that request and answer with submitSystemPasskeyResponse(registrationResponseJson), or declineSystemPasskey() if the user backs out. The rest of the flow is unchanged. Sign-in on those devices then runs the face report through startPendingFaceReportFlow(); see Passkeys and the face report.

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. In a tenant with Face PKI, every path also seals the user's post-quantum keys into the face token it mints; your app does nothing extra. The other two paths 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.