Skip to main content
Version: Next

Managing tokens

The authentication system uses token managers to handle authentication tokens. Token managers are responsible for issuing, validating, revoking, and listing authentication tokens.

Default Token Managers​

Serverpod provides two built-in token managers:

Using the token managers​

After configuring at least one token manager using the pod.initializeAuthServices() method, you can access the token manager instance using the AuthServices.instance.tokenManager property.

final tokenManager = AuthServices.instance.tokenManager;

It will return a MultiTokenManager instance that combines all the token managers configured for listing, validating and revoking tokens.

The MultiTokenManager is a composite token manager that is automatically created when initializing the authentication services and combines multiple token managers. It:

  • Uses the primary token manager for issuing new tokens.
  • Validates tokens against all managers (primary and additional).
  • Delegates management operations to all managers.

Token Validation Flow​

When validating a token, the MultiTokenManager:

  1. Tries the primary token manager first.
  2. If validation fails, tries each additional token manager in order.
  3. Returns the first successful validation result.
  4. Returns null if all managers fail to validate.

This allows you to support multiple token types simultaneously, which is useful for:

  • Migrating from one token type to another.
  • Supporting legacy tokens alongside new tokens.
  • Using different token types for different use cases.

Token Lifecycle Management​

Issuing Tokens​

Tokens are issued automatically by identity providers when users authenticate. You can also issue tokens programmatically:

final authSuccess = await AuthServices.instance.tokenManager.issueToken(
  session,
  authUserId: userId,
  method: 'custom',
  scopes: {Scope.admin},
);

Attaching metadata to tokens​

It is possible to attach metadata to tokens using either global callbacks configured on each token manager or by inserting a metadata row right after issuing the token. For more details, see the specific configuration sections for Server-Side Sessions and JWT.

Validating Tokens​

Tokens are validated automatically by the authentication handler. You can also validate tokens manually:

final authInfo = await AuthServices.instance.tokenManager.validateToken(
  session,
  token,
);

if (authInfo != null) {
  // Token is valid
  final userId = authInfo.userIdentifier;
} else {
  // Token is invalid or expired
}

Revoking Tokens​

Revoke specific tokens by token ID:

await AuthServices.instance.tokenManager.revokeToken(
  session,
  tokenId: 'token-id-here',
);

When using custom metadata on Server-Side Sessions or JWT, you can obtain token IDs from your metadata tables (for example, by device or user agent) and pass them to revokeToken to revoke by that criteria.

Revoke all tokens for a user:

await AuthServices.instance.tokenManager.revokeAllTokens(
  session,
  authUserId: userId,
);

Revoke tokens by method:

await AuthServices.instance.tokenManager.revokeAllTokens(
  session,
  authUserId: userId,
  method: 'email',
);

Listing Tokens​

List all tokens for a user:

final tokens = await AuthServices.instance.tokenManager.listTokens(
  session,
  authUserId: userId,
);

for (final token in tokens) {
  print('Token: ${token.tokenId}, Method: ${token.method}');
}

List tokens by method (i.e. "google", "email", "apple", etc.):

final tokens = await AuthServices.instance.tokenManager.listTokens(
  session,
  authUserId: userId,
  method: 'google',
);

Accessing Specific Token Managers​

In case more than one token manager is configured, you can access specific token manager types from the AuthServices instance using the getTokenManager<T>() method.

final jwtManager = AuthServices.getTokenManager<JwtTokenManager>();
final sessionManager = AuthServices.getTokenManager<ServerSideSessionsTokenManager>();