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

See also

• AuthyraClient API →
• Token Refresh guide →
• Quick Start →