Docs
⌘K

Kotlin: Authentication

Sign app users in with passwords, magic links, SMS and email codes, OAuth/SSO and passkeys; keep and refresh the session; handle deep links with the Kotlin SDK.

Updated Oct 24, 2026

Sign app users in with passwords, magic links, SMS and email codes, OAuth/SSO and passkeys; keep and refresh the session; handle deep links. Every call runs as the client's signed-in user, so your project's policies and row-level security apply. Types and members are listed in source order; each one links to its HTTP endpoint where it maps to one.

#Types and members

SovariaAuth

Sign-in, sign-up and the session for an app user. Mirrors the Dart/Swift/TS/Python clients.

class SovariaAuth(private val client: Sovaria)

SovariaAuth.changes

Emits sign-in / refresh / sign-out events (collect to update UI).

val changes: SharedFlow<AuthState> get()

Each new collector first gets AuthEvent.INITIAL_SESSION with the current session (null when signed out), as in Dart and TypeScript.

SovariaAuth.currentSession

A property.

val currentSession: Session? get()

SovariaAuth.passkeys

Passkeys (WebAuthn): add one for the signed-in user, sign in with one, list and remove them.

val passkeys: SovariaPasskeys by lazy

SovariaAuth.restoreSession

suspend fun restoreSession(): Session?

SovariaAuth.currentAccessToken

The token to sign requests with: the session's (refreshed first when near expiry) or null.

suspend fun currentAccessToken(): String?

SovariaAuth.refreshSession

suspend fun refreshSession(silent: Boolean = false): Session?

SovariaAuth.signUp

suspend fun signUp(email: String, password: String, name: String = ""): Map<String, Any?>

SovariaAuth.signInWithPassword

suspend fun signInWithPassword(email: String, password: String, captchaToken: String? = null): Session

SovariaAuth.signInAnonymously

suspend fun signInAnonymously(): Session

SovariaAuth.verifyMfa

suspend fun verifyMfa(code: String, method: String = ""): Session

SovariaAuth.sendSmsOtp

suspend fun sendSmsOtp(phone: String)

SovariaAuth.verifySmsOtp

suspend fun verifySmsOtp(phone: String, code: String): Session

SovariaAuth.verifyEmailCode

suspend fun verifyEmailCode(email: String, code: String): Session

SovariaAuth.resetPasswordForEmail

Email a password-reset link (PKCE-bound when it opens your app).

suspend fun resetPasswordForEmail(email: String, redirectTo: String? = null, pkce: Boolean? = null)

SovariaAuth.confirmPasswordReset

Set the new password with the token from a type=recovery link.

suspend fun confirmPasswordReset(token: String, newPassword: String, codeVerifier: String? = null)

SovariaAuth.getOAuthSignInUrl

Where the OAuth sign-in should take the user (an app scheme such as com.acme.app://callback, or a web URL).

suspend fun getOAuthSignInUrl(provider: String, redirectTo: String? = null): OAuthStart

Asks for the JSON answer (the route redirects otherwise, which the JDK client doesn't follow) and starts PKCE: the verifier is kept in the session storage until exchangeCodeForSession (audit SDK2-M2).

SovariaAuth.exchangeCodeForSession

Finish an OAuth sign-in with the code from the redirect.

suspend fun exchangeCodeForSession(code: String, codeVerifier: String? = null): Session

The PKCE verifier saved by getOAuthSignInUrl is used when none is passed.

SovariaAuth.listProviders

suspend fun listProviders(): List<Map<String, Any?>>

SovariaAuth.getUser

suspend fun getUser(): Map<String, Any?>

SovariaAuth.listDevices

suspend fun listDevices(): List<Map<String, Any?>>

SovariaAuth.signOut

suspend fun signOut()

AuthLinkResult

What an auth link did. type is sso, magiclink, recovery, signup, email_change_current or email_change_new; session is set when the link signed the user in; for recovery pass token to confirmPasswordReset with the new password.

class AuthLinkResult(val type: String, val session: Session? = null, val token: String? = null,
                     val error: String? = null, val errorDescription: String? = null)

OAuthStart

class OAuthStart(val url: String, val codeVerifier: String?)

Pkce

A PKCE pair (RFC 7636, S256): keep verifier on the device, send challenge with the request.

class Pkce private constructor(val verifier: String, val challenge: String)

Pkce.generate

A fresh pair from 32 random bytes (a 43-character verifier).

fun generate(): Pkce

Pkce.challengeFor

BASE64URL(SHA-256(verifier)) without padding.

fun challengeFor(verifier: String): String

SovariaPasskeys

Passkey calls. Run the platform ceremony with Android's Credential Manager (CreatePublicKeyCredentialRequest / GetPublicKeyCredentialOption), which takes and returns WebAuthn JSON: pass it the options from a start… call and send its JSON to the matching finish… call.

class SovariaPasskeys internal constructor(private val client: Sovaria, private val auth: SovariaAuth)

SovariaPasskeys.startRegistration

Registration options (WebAuthn JSON) for a new passkey for the signed-in user.

suspend fun startRegistration(name: String = ""): Map<String, Any?>

SovariaPasskeys.finishRegistration

Save the passkey the authenticator created (its WebAuthn JSON).

suspend fun finishRegistration(credential: Map<String, Any?>, name: String = ""): Map<String, Any?>

SovariaPasskeys.startSignIn

Sign-in options.

suspend fun startSignIn(userId: String? = null): SignInStart

Pass userId to offer only that user's passkeys.

SovariaPasskeys.finishSignIn

Verify the signed challenge and sign the user in (two-factor when the device checked the user).

suspend fun finishSignIn(challengeId: String, credential: Map<String, Any?>): Session

SovariaPasskeys.list

The signed-in user's passkeys: id, name, created_at, last_used_at.

suspend fun list(): List<Map<String, Any?>>

SovariaPasskeys.remove

Remove one of the signed-in user's passkeys.

suspend fun remove(passkeyId: String)

SignInStart

class SignInStart(val challengeId: String, val options: Map<String, Any?>)

Session

A signed-in app user's tokens.

class Session(
    val accessToken: String,
    val refreshToken: String,
    val expiresAt: Instant,
    /** The full token response (actor lane, MFA flags, …), minus the refresh token. */
    val raw: Map<String, Any?> = emptyMap(),
)

Session.userId

The user id (sub of the access token).

val userId: String? get()

Session.claims

The access token's claims (not verified here; the server verifies on every request).

val claims: Map<String, Any?> get()

Session.expiresWithin

fun expiresWithin(marginSeconds: Long, now: Instant = Instant.now()): Boolean

Session.toJson

fun toJson(): Map<String, Any?>

Session.fromTokens

fun fromTokens(tokens: Map<String, Any?>, now: Instant = Instant.now()): Session

Session.fromJson

fun fromJson(json: Any?): Session?

SessionStorage

Where the client keeps the session across launches. Use the Keystore in apps; the default keeps it in memory only (lost on relaunch).

interface SessionStorage

SessionStorage.read

suspend fun read(key: String): String?

SessionStorage.write

suspend fun write(key: String, value: String)

SessionStorage.delete

suspend fun delete(key: String)

MemorySessionStorage

class MemorySessionStorage : SessionStorage

MemorySessionStorage.read

override suspend fun read(key: String)

MemorySessionStorage.write

override suspend fun write(key: String, value: String)

MemorySessionStorage.delete

override suspend fun delete(key: String)

SovariaDevice

The device a session belongs to (sent as headers so sign-outs and attestation can target it).

class SovariaDevice(val id: String, val platform: String, val name: String = "")

SovariaDevice.headers

A property.

val headers: Map<String, String>

AuthEvent

enum class AuthEvent

AuthState

class AuthState(val event: AuthEvent, val session: Session?)

Related

Kotlin SDKAndroid quickstart (Kotlin)JavaScript SDK