Authentication

RakomiAuth is the top-level actor for every sign-in flow. Construct it from a RakomiAuthConfiguration — either directly, or installed for you by the RakomiProvider SwiftUI modifier.

let auth = RakomiAuth(configuration: configuration)

RakomiAuth.shared is a convenience accessor for SwiftUI apps that mount .rakomi(configuration:) once at the root — it is not a process-global singleton; each configuration gets its own instance, and RakomiAuth.instance(for:) looks one up by publishable key.

Email & password

await auth.signIn(email: "user@example.com", password: "••••••••")
await auth.signUp(email: "user@example.com", password: "••••••••")
await auth.signOut()

None of these throw — outcomes (including failures) are observed on the authStateChanges stream described in Session & tokens. signOut() clears local state immediately and best-effort revokes the session server-side; it never blocks on the network.

Social sign-in

await auth.signIn(withProvider: .google)

SocialProvider is a CaseIterable enum: .google, .github, .microsoft, .apple, .discord, .facebook, .slack, .twitter, .gitlab, .linkedin. It is intentionally not @frozen — future providers are additive.

The flow launches the system browser (ASWebAuthenticationSession under the hood, per RFC 8252 — never an embedded web view) with a PKCE S256 challenge, and completes when your app receives the OAuth callback on redirectURI. Wire the callback through to the SDK:

// SwiftUI
.onOpenURL { url in
    Task { await auth.handleCallbackURL(url) }
}

RakomiProvider (below) wires this for you automatically.

Sign in with Apple

RakomiAppleSignInButton is a SwiftUI view wrapping Apple’s native SignInWithAppleButton — it requests the full name and email scopes and exchanges the resulting identity token through the same OAuth callback path as every other social provider. See Installation for the required capability.

tvOS device authorization

tvOS cannot use ASWebAuthenticationSession (a shared-screen device restriction), so it uses the OAuth 2.0 device authorization grant (RFC 8628) instead:

let start = try await auth.startDeviceAuthorization()
// Display start.userCode + start.verificationURI to the viewer;
// they enter the code on their phone or computer.
// The SDK polls in the background and transitions authStateChanges
// to .authenticated on approval.

RakomiDeviceCodeView is a pre-built SwiftUI view that does the display and polling automatically.

MFA step-up (TOTP)

When a sign-in requires a second factor, the SDK emits an AuthEvent.mfaChallengeRequired(challengeId:) and an AuthState.error carrying SdkErrorReason.mfaStepUpRequired (see Errors). Complete the challenge with a 6-digit TOTP code:

await auth.verifyMfa(challengeId: challengeId, code: "123456")

The code must be exactly 6 numeric characters; the SDK validates the format locally before making a network call.

Biometric unlock

await auth.unlockWithBiometric(reason: "Unlock to continue")

Prompts the platform biometric gate (Face ID / Touch ID via LocalAuthentication) and, on success, re-hydrates the session from local storage. This is an additional, on-demand path into hydration — the SDK does not gate ordinary token retrieval behind a biometric prompt on its own; see Session & tokens for what does and doesn’t require it. Biometric unlock always reports unavailable on watchOS and tvOS.

Pre-built SwiftUI views

All of these require iOS 17 / macOS 14 / watchOS 10 / tvOS 17 / visionOS 1 (they use Swift’s @Observable macro) — see Platform support.

ContentView()
    .rakomi(configuration: configuration)

View	Purpose
RakomiProvider (.rakomi(configuration:) modifier)	Mount at your app’s root. Hydrates the session, installs the deep-link listener (.onOpenURL), and injects the auth environment for the rest of this table.
RakomiAuthGate	Switches between signedIn / signedOut / loading / error view builders based on the current AuthState.
RakomiSignInForm	Email/password form with built-in social-provider buttons and inline TOTP step-up.
RakomiSignInButton(provider:)	A single social sign-in button for one SocialProvider.
RakomiAppleSignInButton	Native SignInWithAppleButton wrapper (see above).
RakomiUserAvatar	Displays the signed-in user’s avatar, or a placeholder when signed out.
RakomiDeviceCodeView	tvOS device-authorization display + polling (see above).

Every view reads from the environment RakomiProvider installs, so a plain Environment lookup — not a constructor parameter — is how a custom view reaches the current user or auth state.

Branding

Pre-built views accept a RakomiBranding (primary/on-primary/background colors, logo URL) through the same environment. Branding is validated at runtime against WCAG 2.2 AA contrast (≥4.5:1) before being applied; branding that fails the check silently falls back to the SDK default rather than rendering illegible UI.

UIKit / AppKit

SwiftUI is not required. RakomiAuthUIKitObserver.attach(_:) forwards every state transition to NotificationCenter under Notification.Name.rakomiAuthStateChanged, carrying the state name, the signed-in user’s id, and (on error) the error’s stable wire-level reason string — deliberately never a token, since NotificationCenter posts are process-global and reach anything else linked into your app.

let observer = RakomiAuthUIKitObserver.attach(auth)
// observer.cancel() on teardown

Obtain a token only through await auth.getToken(), which is access-controlled by holding the RakomiAuth instance — never through the notification.

Next steps

• Session & tokens — AuthState, AuthEvent, refresh, and storage.
• Errors — every SdkErrorCode / SdkErrorReason.