Token class

An immutable OAuth-style token pair.

expiresAt is optional: not all auth schemes expose lifetime information. When it's null, the token is considered non-expiring and proactive refresh is disabled for it.

metadata carries arbitrary extra claims — tenant IDs, user IDs, feature flags, or any non-standard JWT payload fields. tryParseJwt populates it automatically from non-standard claims, while the standard claims sub, iss, and iat are surfaced as first-class typed fields.

Constructors

Token({required String accessToken, String? refreshToken, DateTime? expiresAt, List<String> scopes = const [], Map<String, dynamic> metadata = const {}, String? subject, String? issuer, DateTime? issuedAt}): Creates an immutable Token.
const
Token.fromJson(Map<String, dynamic> json): Reconstructs a Token from its toJson form.
factory

Properties

accessToken → String: Bearer token used to authenticate requests.
final
expiresAt → DateTime?: Absolute expiry of accessToken. null means unknown / non-expiring.
final
hashCode → int: The hash code for this object.
no setterinherited
issuedAt → DateTime?: The iat (issued-at) claim from the JWT — when the token was minted.
final
issuer → String?: The iss (issuer) claim from the JWT — identifies who issued the token.
final
maskedAccessToken → String: Returns a partially-redacted form of accessToken suitable for logs.
no setter
metadata → Map<String, dynamic>: Arbitrary extra data associated with this token.
final
props → List<Object?>: The list of properties that will be used to determine whether two instances are equal.
no setter
refreshToken → String?: Long-lived token used to obtain a new accessToken. May be null for flows that do not issue refresh tokens (e.g. client-credentials).
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scopes → List<String>: Scopes granted with this token.
final
stringify → bool: If set to true, the toString method will be overridden to output this instance's props.
no setter
subject → String?: The sub (subject) claim from the JWT — typically a user or service ID.
final

Methods

age([DateTime? now]) → Duration?: Returns the elapsed time since issuedAt.
copyWith({String? accessToken, String? refreshToken, DateTime? expiresAt, List<String>? scopes, Map<String, dynamic>? metadata, String? subject, String? issuer, DateTime? issuedAt, bool clearRefreshToken = false, bool clearExpiresAt = false, bool clearSubject = false, bool clearIssuer = false, bool clearIssuedAt = false}) → Token: Returns a copy with the supplied fields replaced.
expiresInSeconds([DateTime? now]) → int?: Returns the number of whole seconds until expiresAt, mirroring the OAuth 2.0 expires_in field used in token responses.
hasAllScopes(List<String> required) → bool: Returns true if all of required are present in scopes.
hasAnyScope(List<String> any) → bool: Returns true if at least one of any is present in scopes.
hasScope(String scope) → bool: Returns true if scope is present in scopes.
isExpired([DateTime? now]) → bool: Returns true if expiresAt is non-null and not in the future.
isValid([DateTime? now]) → bool: Returns true when the token is NOT expired.
isValidWithAllScopes(List<String> required, [DateTime? now]) → bool: Returns true if the token is valid and has all of required scopes.
isValidWithAnyScope(List<String> any, [DateTime? now]) → bool: Returns true if the token is valid and has at least one of any scopes.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
remainingLifetime([DateTime? now]) → Duration?: Returns the time remaining until expiresAt.
requiresRefresh({Duration window = const Duration(minutes: 5), DateTime? now}) → bool: Returns true if the token should be refreshed soon.
toJson() → Map<String, dynamic>: JSON representation suitable for any TokenStorage backend.
toString() → String: A string representation of this object.
willExpireWithin(Duration duration, [DateTime? now]) → bool: Returns true if the token will expire within duration from now.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

fromJsonOrNull(Map<String, dynamic> json) → Token?: Like fromJson but returns null on any parse error instead of throwing. Prefer this at storage boundaries where the persisted data may be stale or corrupt.
tryParseJwt(String jwt, {String? refreshToken}) → Token?: Parses a JWT jwt and returns a Token seeded with the exp, iat, sub, iss, and scope / scopes / scp claims found in the payload.