Configuration

AuthConfig is an immutable value object passed to AuthyraClient to control token lifecycle behaviour. All fields have sensible defaults, only override what your app needs.

Defaults

const AuthConfig(
  tokenLifetime:      3600,  // 1 hour
  autoRefresh:        true,
  refreshBeforeExpiry: 300,  // 5 minutes
)

Usage

Pass AuthConfig when constructing AuthyraClient:

await Authyra.initialize(
  client: AuthyraClient(
    providers: [myProvider],
    storage: SecureAuthStorage(),
    config: const AuthConfig(
      tokenLifetime:       1800,  // 30-minute tokens
      refreshBeforeExpiry:  120,  // Refresh 2 minutes early
    ),
  ),
);

tokenLifetime

The nominal lifetime of an access token in seconds, used as a fallback when the provider's sign-in response does not include an explicit expiry.

When a provider returns expires_in (OAuth2) or expiresAt (credentials), the server-reported value always takes precedence. tokenLifetime only applies when expiry information is absent.

// 30-minute tokens for a high-security backend
const AuthConfig(tokenLifetime: 1800)

// 24-hour tokens for a long-lived session API
const AuthConfig(tokenLifetime: 86400)

autoRefresh

Controls whether AuthyraInstance proactively refreshes the access token before it expires.

When true, the instance schedules a timer that fires refreshBeforeExpiry seconds before the token expires and silently calls provider.refreshToken(). The authStateChanges stream emits an updated AuthState.authenticated with the fresh token, no user interaction needed.

When false, token refresh is entirely manual:

// Check and refresh manually
final session = await Authyra.instance.getSession();
if (session?.shouldRefresh ?? false) {
  await Authyra.instance.refreshSession();
}

Disable autoRefresh in backend and CLI contexts where no event loop is running continuously, or where you manage token renewal through your own middleware.

// Backend service, manage refresh explicitly
const AuthConfig(autoRefresh: false)

refreshBeforeExpiry

How many seconds before the access token expires to trigger a proactive refresh. Only applies when autoRefresh: true.

const AuthConfig(
  autoRefresh: true,
  refreshBeforeExpiry: 120,  // Refresh 2 minutes before expiry
)

The underlying AuthSession.shouldRefresh predicate uses this value via AuthConfig.refreshThreshold:

session.shouldRefresh  // true when DateTime.now() > expiresAt - refreshThreshold

A larger value gives more buffer against clock drift and network latency at the cost of slightly shorter effective token lifetimes. The default (300 s) works well for 1-hour tokens.

copyWith

Derive environment-specific configs from a base:

const base = AuthConfig();

// Development, disable refresh to avoid background timers in tests
final devConfig = base.copyWith(autoRefresh: false);

// Production, shorter effective token window for higher security
final prodConfig = base.copyWith(refreshBeforeExpiry: 120);

Serialisation

AuthConfig can be serialised to/from JSON, useful for remote config or persisting alongside session data:

final json = const AuthConfig().toJson();
// {"tokenLifetime": 3600, "autoRefresh": true, "refreshBeforeExpiry": 300}

final config = AuthConfig.fromJson(json);

Missing fields fall back to defaults, so fromJson is forward-compatible with older persisted configs.

Recommended presets