Authentication

AuthStore runs the authentication ceremony: the steps a person goes through to sign in to an account, to recover an account, or to confirm that it is really them before a sensitive operation. Folio decides which steps the person sees. The SDK asks Folio for the next step, tells your app what to show through the store state, and sends the answer your app collects back to Folio. Your app draws the screens; it does not choose a method or build a request.

When a sign-in or a recovery finishes, the SDK switches the session to the account. You see the new identity in SessionStore.

How it worksCopy Anchor Link

1. Mount AuthStore on the runtime.
2. Dispatch Start with what the person wants to do: sign in, recover an account or verify.
3. The state moves to Busy while the SDK talks to Folio, then to AwaitingInput with a phase: the input to ask for, such as a password or a one-time code.
4. Show the input for that phase and dispatch Answer with what the person entered. The ceremony can ask for several phases in a row.
5. The ceremony ends in Authenticated, or in Failed with an error. A new account first passes through AwaitingRecoveryCodeAck to show its recovery code.

let auth = try AuthStore.mount(runtime: sdk)

try auth.dispatch(action: .start(value: .signIn(value: .withIdentifier(
    identifier: .email(value: "person@example.com")
))))

let flow = auth.$state
    .map(\.flow)
    .sink { flow in
        switch flow {
        case .idle, .busy:
            showSpinner()
        case let .awaitingInput(phase, alternatives, error):
            showInput(phase, alternatives, error)
        case let .awaitingRecoveryCodeAck(code):
            showRecoveryCode(code)
        case .authenticated:
            closeSignIn()
        case let .failed(error):
            showFailure(error)
        }
    }

try auth.dispatch(action: .answer(value: .otp(value: "123456")))

AuthStore takes no init value. It does not have to stay mounted while your app uses the session: the runtime itself ends a session that Folio has ended. See Expired sessions.

On iOS AuthStore is an ObservableObject that publishes its state as @Published state, updated on the main actor; on Android state is a StateFlow<AuthUiModel>; on the web read state and register a listener with subscribe, which returns the function that removes it. mount takes the runtime, a FolioSdk. Close the store with close() when you no longer need it.

ReactCopy Anchor Link

On the web, useAuthStore from @folio/sdk/stores mounts AuthStore for the component that calls it. It needs a FolioSDKProvider from @folio/sdk/provider above that component.

import { useAuthStore } from '@folio/sdk/stores';
import { AuthAction, AuthAnswer } from '@folio/sdk';

function SignIn() {
    const { store, state } = useAuthStore();
    if (store === undefined || state === undefined) return null;
    const { flow } = state;
    if (flow.type !== 'AWAITING_INPUT' || flow.value.phase.type !== 'OTP') return null;
    return (
        <form
            onSubmit={(event) => {
                event.preventDefault();
                const code = new FormData(event.currentTarget).get('code');
                store.dispatch(AuthAction.answer(AuthAnswer.otp(String(code))));
            }}
        >
            <input name="code" maxLength={flow.value.phase.value.length} />
            {flow.value.phase.value.canResend && (
                <button type="button" onClick={() => store.dispatch(AuthAction.resendOtp)}>
                    Send a new code
                </button>
            )}
        </form>
    );
}

useAuthStore returns { store, state }. Both are undefined until the store is mounted after the first render. The hook re-renders the component on every state change, and closes the store when the component unmounts or the runtime changes. Every component that calls useAuthStore mounts its own AuthStore. Call it once, in the component that holds the sign-in screens, and pass store and state down to them.

ActionsCopy Anchor Link

An action that does not fit the current state does nothing. For example, SelectAlternative and CompleteDeviceLink do nothing when no step is waiting for input, and AcknowledgeRecoveryCode does nothing outside AwaitingRecoveryCodeAck. ResendOtp also acts while a sign-in or a recovery is Busy: it restarts that ceremony for the same identifier, as long as the ceremony was started with one.

Start a ceremonyCopy Anchor Link

AuthStart says what the ceremony is for.

NewSession is Anonymous, which starts the sign-in without an identifier, or WithIdentifier { identifier }, which starts it for an email address or a phone number. The identifier is an AuthIdentifierInput: Email { value } or Phone { value }.

A Recovery started while a sign-in is waiting for input continues from that sign-in.

StateCopy Anchor Link

The state of the store is AuthUiModel. Its field flow is an AuthFlowStep; dataRegions and dataRegion describe the data region choice of a sign-up, see Data region.

Authenticated stays until you start or cancel another ceremony. The identity the sign-in or recovery ended on reaches SessionStore: Authenticated with the account's user id and email address, or Transient when Folio signed the person in to a guest account. If the SDK cannot switch the session to that identity, for example because the services for it cannot start, the flow moves on from Authenticated to Failed with SessionUnavailable, and SessionStore reports the previous identity again with status Device (see SessionStatus). A verification does not change the identity.

PhasesCopy Anchor Link

AuthPhase is the input the current step waits for.

AuthSocialProvider is Google, Apple, Microsoft, Github or Facebook. It is spelled like AuthMethod: see Alternatives.

The numeric fields have these types:

freshDevicePlatform is a Platform value that describes this device, such as its operating system.

Some accounts ask for two inputs in one step. When a step needs a password and an authenticator code, the phase is first Password; after the password the phase becomes Totp, and the SDK sends both together when you answer the code. When a step needs a passkey and a password, the phase is Password and the SDK runs the passkey dialog when you answer with the password.

AnswersCopy Anchor Link

AuthAnswer is the input you send with Answer. Send the answer that matches the current phase: an answer for another phase is not sent, and the step reports the error Unknown.

Passwords and recovery codes never leave the device as entered: the SDK derives what Folio needs from them on the device.

External providersCopy Anchor Link

The SDK passes authorizationUrl through and never opens it: opening the provider's page, for example in the system browser or an authentication session, and catching the redirect back to your app are up to you. The SocialRedirect answer names the provider and the redirect URI the provider returns to. The SocialCallback answer carries the authorization code from that redirect and the state it echoes, which must be the state of the SocialRedirect phase.

Integrator attestationCopy Anchor Link

Folio asks for an integrator attestation when an account is signed up through an integrator. The SDK neither creates nor checks it, and FolioSdkConfig has no setting for it: the integrator that integratorId names issues it from its backend. It is a signed JWT that asserts the person's identity and carries the nonce of the phase, signed with the key the integrator registered with Folio. Fetch it from that backend and send it unchanged as the IntegratorAttestation answer; Folio checks the signature against the registered key.

AlternativesCopy Anchor Link

alternatives in AwaitingInput lists the other methods, as AuthMethod values, that the person may use for the current step instead of the one in phase. Dispatch SelectAlternative with one of them to switch; the state moves to AwaitingInput with the phase of that method.

AuthMethod is Password, Otp, Totp, RecoveryCode, NewPassword, SocialRedirect, SocialCallback, IntegratorAttestation, Passkey or DeviceApproval.

AuthMethod, AuthSocialProvider, OtpChannel and VerificationOperationType have cases without fields and follow one pattern, shown here for AuthMethod:

On the web these are objects, not strings: compare their type, for example method.type === 'PASSKEY'.

PasskeysCopy Anchor Link

A passkey has no phase of its own, because the system shows the passkey dialog. When alternatives contains Passkey, offer a button such as "Use a passkey" and dispatch SelectAlternative with Passkey: the state moves to Busy while the dialog is shown, then on to the next step. When a step offers only a passkey, the SDK opens the dialog by itself.

The SDK offers passkeys only on a device that supports them. It checks once when the runtime starts; until then, and on a device without passkey support, Passkey is not in alternatives. When a step can only be completed with a passkey and the device has no passkey support, the ceremony ends in Failed with Unsupported.

if case let .awaitingInput(_, alternatives, _) = auth.state.flow, alternatives.contains(.passkey) {
    try auth.dispatch(action: .selectAlternative(method: .passkey))
}

When the person closes the passkey dialog, the step reports PasskeyCancelled; when the passkey fails, it reports PasskeyFailed. The person can try again or choose another method.

One-time codesCopy Anchor Link

The Otp phase describes where the code was sent:

ResendOtp starts the sign-in or the recovery again with the identifier it was started with, which makes Folio send a new code. It does nothing for a ceremony started without an identifier and for a verification. Show a resend button only when canResend is true.

Recovery codesCopy Anchor Link

When a ceremony creates the credentials of an account, the SDK also creates a recovery code for it. Before the ceremony finishes, the state is AwaitingRecoveryCodeAck with the code. Show the code, ask the person to store it somewhere safe, and dispatch AcknowledgeRecoveryCode. Only then does the state become Authenticated and the session switch to the account. The person uses this code later to recover the account in the RecoveryCode phase.

VerificationCopy Anchor Link

Some operations need a fresh confirmation that the person who is signed in is really them. Start such a confirmation with Start and AuthStart.Verification. It runs the same phases as a sign-in and ends in Authenticated; it does not change the session's identity.

VerificationRequirement has one optional field, operation:

• Without operation, the verification confirms the person for the account in general.
• With operation, a VerificationOperation, the verification is bound to one operation.

let operation = VerificationOperation(
    operationType: .deleteAccount,
    binding: binding,
    displayText: nil
)
try auth.dispatch(action: .start(value: .verification(value: VerificationRequirement(
    operation: operation
))))

On Android displayText defaults to null and operation to null, so VerificationRequirement() starts a verification without an operation. On the web VerificationRequirement and VerificationOperation are plain objects in which every field must be present; pass undefined for a field you leave out.

Data regionCopy Anchor Link

A sign-up screen can let the person pick where the documents of a new account are stored. dataRegions lists the options in display order, European Union first, then United States. Each DataRegionOption has region, a DataRegion (.eu and .us in Swift, EU and US in Kotlin and TypeScript), title, the name to show in the SDK locale, and selected. dataRegion is the region picked so far, or none. Dispatch SelectDataRegion when the person taps an option; the store only records the choice. In this version the SDK does not send the region to Folio, and no phase of the ceremony waits for it. Start and Cancel clear the choice.

Device approvalCopy Anchor Link

In the DeviceApproval phase, Folio asks for this sign-in to be approved from a device where the person is already signed in. The phase carries the id of the approval request (challengeId), the fingerprint and platform of this device (freshDeviceFingerprint, freshDevicePlatform) and how long the request stays valid (expiresInSeconds). When the approval arrives, dispatch CompleteDeviceLink with the challenge id and the transfer acknowledgement of the approval. CompleteDeviceLink does nothing when the current step offers no device approval.

transferAck is a signature that the trusted device produces when it approves the request and hands over the account key. FolioSDK has no API that produces or receives it; Folio's own app does this on the trusted device. An app built on FolioSDK alone cannot answer this phase: offer the methods in alternatives, or dispatch Cancel.

ErrorsCopy Anchor Link

AuthError appears in two places:

• In AwaitingInput.error, when the step is still open and the person can answer again.
• In Failed.error, when the ceremony is over.

An error that would leave a step open is reported in Failed instead when there is no step to go back to, for example when Start itself fails. A failure the SDK cannot classify while a Password, Otp, Totp, RecoveryCode or NewPassword phase waits is reported as that phase's wrong-input error, WrongPassword, WrongCode, WrongRecoveryCode or WeakPassword, instead of Unknown.

until is a time in seconds since the Unix epoch: an Int64? on iOS, a Long? on Android and a bigint | undefined on the web. retryAfter is a number of seconds: a UInt64? on iOS, a Long? on Android and a bigint | undefined on the web. capability and message are strings.

dispatch itself fails with a CoreError when the store cannot take the action, for example after the runtime was shut down. For what a closed store throws, see Store errors.

See alsoCopy Anchor Link

• Session: the identity the ceremony signs in, and sign-out.
• Errors: errors shared by all stores.