Dart: Authentication

#AuthLinkResult.AuthLinkResult

Create an instance.

const AuthLinkResult({required this.type, this.session, this.token, this.error, this.errorDescription})

#AuthLinkResult.type

sso, magiclink, recovery, signup, email_change_current, email_change_new.

final String type

#AuthLinkResult.session

Set when the link signed the user in (sso, magiclink).

final Session? session

#AuthLinkResult.token

For recovery: pass it to SovariaAuth.confirmPasswordReset with the new password.

final String? token

#AuthLinkResult.error

A property.

final String? error

#AuthLinkResult.errorDescription

A property.

final String? errorDescription

#OAuthStart.OAuthStart

Create an instance.

const OAuthStart(this.url, this.verifier)

#OAuthStart.url

A property.

final Uri url

#OAuthStart.verifier

Kept in the client's storage too; only needed if you exchange the code yourself.

final String verifier

#SovariaAuth.SovariaAuth

Create an instance.

SovariaAuth(this._client)

#SovariaAuth.passkeys

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

late final SovariaPasskeys passkeys

#SovariaAuth.currentSession

The signed-in user's session, or null.

Session? get currentSession

#SovariaAuth.currentUserId

The signed-in user's id, or null.

String? get currentUserId

#SovariaAuth.onAuthStateChange

Sign-in, refresh and sign-out events.

Stream<AuthState> get onAuthStateChange

New listeners get the current state first.

#SovariaAuth.restoreSession

Load the stored session (called by Sovaria.initialize).

Future<Session?> restoreSession()

#SovariaAuth.currentAccessToken

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

Future<String?> currentAccessToken()

#SovariaAuth.signUp

Create an account and sign in.

Future<Map<String, Object?>> signUp({required String email, required String password, String name = ""})

When the project requires email confirmation the result has email_verification_required: true and there is no session until the user confirms.

HTTP

POST /api/v1/auth/register

#SovariaAuth.signInWithPassword

Future<Session> signInWithPassword({required String email, required String password, String? captchaToken})

HTTP

POST /api/v1/auth/project/login

#SovariaAuth.signInAnonymously

A guest user (when Anonymous sign-in is on for the project).

Future<Session> signInAnonymously()

HTTP

POST /api/v1/auth/project/anonymous

#SovariaAuth.verifyMfa

Finish sign-in with a TOTP (or SMS) code after mfaRequired.

Future<Session> verifyMfa(String code, {String method = ""})

#SovariaAuth.sendSmsOtp

Text a 6-digit code to phone (E.164, e.g.

Future<void> sendSmsOtp(String phone)

+919876543210).

HTTP

POST /api/v1/auth/otp/send

#SovariaAuth.verifySmsOtp

Future<Session> verifySmsOtp({required String phone, required String code})

#SovariaAuth.sendMagicLink

Email a sign-in link plus a 6-digit code.

Future<void> sendMagicLink(String email, {String? redirectTo, bool? pkce, String? captchaToken})

A link that opens your app (redirectTo with your app's scheme, or a registered app link with pkce) is bound to this install with PKCE.

HTTP

POST /api/v1/auth/magic-link/send

#SovariaAuth.verifyMagicLink

Sign in with the token from a magic link (usually via handleDeepLink).

Future<Session> verifyMagicLink(String token, {String? codeVerifier})

HTTP

POST /api/v1/auth/magic-link/verify

#SovariaAuth.verifyEmailCode

Sign in with the 6-digit code from the sign-in email.

Future<Session> verifyEmailCode({required String email, required String code})

HTTP

POST /api/v1/auth/magic-link/verify-code

#SovariaAuth.resetPasswordForEmail

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

Future<void> resetPasswordForEmail(String email, {String? redirectTo, bool? pkce})

HTTP

POST /api/v1/auth/password-reset/send

#SovariaAuth.confirmPasswordReset

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

Future<void> confirmPasswordReset({required String token, required String newPassword, String? codeVerifier})

HTTP

POST /api/v1/auth/password-reset/confirm

#SovariaAuth.getOAuthSignInUrl

The URL to open for "Sign in with provider" (Google, Apple, GitHub, Microsoft, your OIDC provider…).

Future<OAuthStart> getOAuthSignInUrl(String provider, {String? redirectTo})

The provider sends the user back to redirectTo (your app's scheme or a registered app link) with ?code=…&type=sso; pass that URI to handleDeepLink.

With flutter_web_auth_2:

HTTP

GET /api/v1/auth/sso/{provider_id}/authorize

final start = await sovaria.auth.getOAuthSignInUrl('google', redirectTo: 'com.example.app://auth-callback');
final result = await FlutterWebAuth2.authenticate(url: start.url.toString(), callbackUrlScheme: 'com.example.app');
await sovaria.auth.handleDeepLink(Uri.parse(result));

#SovariaAuth.exchangeCodeForSession

Exchange the one-time code from the redirect for a session.

Future<Session> exchangeCodeForSession(String code, {String? codeVerifier})

HTTP

POST /api/v1/auth/sso/exchange

#SovariaAuth.listProviders

Enabled sign-in providers for your sign-in screen.

Future<List<Map<String, Object?>>> listProviders()

HTTP

GET /api/v1/auth/sso/providers

#SovariaAuth.handleDeepLink

Handle a deep link / universal link that opened the app: provider sign-in (type=sso), magic links, email confirmations; for recovery the token is returned for the new-password screen.

Future<AuthLinkResult?> handleDeepLink(Uri uri)

Returns null when the link isn't an auth link.

#SovariaAuth.refreshSession

Rotate the refresh token now.

Future<Session?> refreshSession({bool silent = false})

Concurrent callers share one request. A refresh token presented twice (stolen copy) makes the server end every session; the user must sign in again.

HTTP

POST /api/v1/auth/refresh

#SovariaAuth.getUser

The signed-in user's profile.

Future<Map<String, Object?>> getUser()

HTTP

GET /api/v1/auth/me

#SovariaAuth.listDevices

Devices this user is signed in on (current: true is this one).

Future<List<Map<String, Object?>>> listDevices()

#SovariaAuth.signOutDevice

Sign another device out (its sessions end now and its push tokens are removed).

Future<void> signOutDevice(String deviceId)

HTTP

POST /api/v1/auth/logout

#SovariaAuth.signOut

Sign out on this device (the refresh token is revoked; requests fall back to the anon key).

Future<void> signOut()

HTTP

POST /api/v1/auth/logout

#SovariaAuth.dispose

Future<void> dispose()

#SovariaPasskeys.startRegistration

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

Future<Map<String, Object?>> startRegistration({String name = ""})

HTTP

POST /api/v1/auth/passkeys/register/start

#SovariaPasskeys.finishRegistration

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

Future<Map<String, Object?>> finishRegistration(Map<String, Object?> credential, {String name = ""})

HTTP

POST /api/v1/auth/passkeys/register/finish

#SovariaPasskeys.startSignIn

Sign-in options.

Future<PasskeySignInStart> startSignIn({String? userId})

Pass userId to offer only that user's passkeys.

HTTP

POST /api/v1/auth/passkeys/authenticate/start

#SovariaPasskeys.finishSignIn

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

Future<Session> finishSignIn(String challengeId, Map<String, Object?> credential)

HTTP

POST /api/v1/auth/passkeys/authenticate/finish

#SovariaPasskeys.list

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

Future<List<Map<String, Object?>>> list()

HTTP

GET /api/v1/auth/passkeys

#SovariaPasskeys.remove

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

Future<void> remove(String passkeyId)

HTTP

DELETE /api/v1/auth/passkeys/{passkey_id}

#PasskeySignInStart.PasskeySignInStart

Create an instance.

const PasskeySignInStart(this.challengeId, this.options)

#PasskeySignInStart.challengeId

A property.

final String challengeId

#PasskeySignInStart.options

A property.

final Map<String, Object?> options

#Session.Session

Create an instance.

Session({required this.accessToken, required this.refreshToken, required this.expiresAt, this.raw = const {}})

#Session.accessToken

A property.

final String accessToken

#Session.refreshToken

A property.

final String refreshToken

#Session.expiresAt

A property.

final DateTime expiresAt

#Session.raw

The full token response (actor lane, MFA flags, …).

final Map<String, Object?> raw

#Session.userId

The user id (sub of the access token).

String? get userId

#Session.claims

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

Map<String, Object?> get claims

#Session.expiresWithin

bool expiresWithin(Duration margin, {DateTime? now})

#Session.Session.fromTokens

Create an instance.

factory Session.fromTokens(Map<String, Object?> tokens, {DateTime? now})

#Session.toJson

Map<String, Object?> toJson()

#Session.fromJson

static Session? fromJson(Object? json)

#SessionStorage.read

Future<String?> read(String key)

#SessionStorage.write

Future<void> write(String key, String value)

#SessionStorage.delete

Future<void> delete(String key)

#MemorySessionStorage.values

A property.

final Map<String, String> values

#MemorySessionStorage.read

Future<String?> read(String key)

#MemorySessionStorage.write

Future<void> write(String key, String value)

#MemorySessionStorage.delete

Future<void> delete(String key)

#SovariaDevice.SovariaDevice

Create an instance.

const SovariaDevice({required this.id, this.name, this.platform, this.appVersion})

#SovariaDevice.id

A property.

final String id

#SovariaDevice.name

A property.

final String? name

#SovariaDevice.platform

ios, android, web, macos, windows, linux or other.

final String? platform

#SovariaDevice.appVersion

A property.

final String? appVersion

#SovariaDevice.headers

A property.

Map<String, String> get headers

#AuthState.AuthState

Create an instance.

const AuthState(this.event, this.session)

#AuthState.event

A property.

final AuthEvent event

#AuthState.session

A property.

final Session? session

#Pkce.verifier

A property.

final String verifier

#Pkce.challenge

A property.

final String challenge

#Pkce.Pkce.generate

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

factory Pkce.generate([Random? random])

#Pkce.challengeFor

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

static String challengeFor(String verifier)

#isAppRedirect

A redirect into an app (custom scheme such as com.example.app://callback).

bool isAppRedirect(String? url)