The Token Service is the central service in Blazorade ID responsible for acquiring, refreshing, and providing tokens to the application. All access tokens used to call protected resources, as well as the identity token representing the signed-in user, are obtained through this service.

Applications never communicate directly with authorization endpoints, token endpoints, refresh tokens, or token storage. Instead, they request tokens from the Token Service, which determines how those tokens are produced based on current state, configuration, and request options.

The Token Service always attempts to satisfy token requests using existing valid tokens before initiating network calls or user interaction.

• Provide access tokens for protected resources based on requested scopes.
• Provide the identity token representing the currently authenticated user.
• Decide whether tokens can be reused, refreshed, or must be newly acquired.
• Coordinate authorization flows when user interaction is required.
• Persist and retrieve tokens using the configured Token Store service.
• Surface authorization failures through the configured notification mechanism.
• Ensure that authentication state changes are propagated to the Blazor authentication infrastructure.

The ITokenService interface defines the following members:

• GetAccessTokensAsync

  Returns zero or more access tokens for the current user that satisfy the requested scopes. The method may return cached tokens, refreshed tokens, or newly acquired tokens depending on availability and prompt behavior. The result is an AccessTokenDictionary keyed by scope combinations.

• GetIdentityTokenAsync

  Returns the identity token representing the currently authenticated user, if available. The method may reuse an existing token, refresh tokens silently, or initiate an authorization flow depending on availability and prompt behavior. If no identity token can be obtained, the method returns null.

When access tokens are requested, the Token Service evaluates each group of requested resource scopes independently. Scopes are first normalized and grouped using the configured Scope Sorter service.

For each scope group, the Token Service follows this process:

• Attempt to retrieve an existing valid access token from the Token Store.
• If no valid token is available and interaction is not required, attempt to refresh tokens using the Token Refresher service.
• If no valid token is available and interaction is allowed, initiate an interactive authorization flow using the Authorization Code Provider service.

If an interactive authorization flow succeeds, all requested scopes are consented in a single operation. The service ensures that interaction is performed at most once per request, even if multiple scope groups are processed.

Access tokens are returned as a dictionary keyed by scope combinations. The dictionary may be empty if no access tokens can be produced under the current conditions.

When an identity token is requested, the Token Service evaluates the request in the following order:

• Attempt to retrieve an existing valid identity token from the Token Store.
• If no valid token is available and interaction is not required, attempt to refresh tokens using the Token Refresher service.
• If no valid token is available and interaction is allowed, initiate an interactive authorization flow using the Authorization Code Provider service.

Only OpenID-related scopes are considered when validating identity tokens. If no identity token can be obtained, the service returns no token, indicating that the user is not authenticated.

Token acquisition behavior is controlled through GetTokenOptions, particularly the Prompt setting.

• When the prompt option disallows interaction, the Token Service operates strictly in silent mode and never triggers UI interaction.
• When interaction is allowed, the Token Service may redirect the user to the authorization endpoint using the configured Authorization Code Provider.

If user interaction fails, for example due to popup blocking or user cancellation, the Token Service does not throw UI-specific errors. Instead, failure information is forwarded to the configured Authorization Code Failure Notifier.

The Token Service is responsible for ensuring that changes to the identity token are reflected in the application's authentication state. When a new identity token is acquired, refreshed, or becomes invalid, the service coordinates with the Blazor authentication infrastructure so that authorization features such as AuthorizeView and the Authorize attribute reflect the current user state. This is done using the Authentication State Notifier service.

Blazorade ID provides a default implementation of the Token Service that coordinates the following services:

• Token Store for token persistence
• Authorization Code Provider for initiating authorization flows
• Authorization Code Processor for exchanging authorization codes for tokens
• Token Refresher for silent token renewal
• Scope Sorter for normalizing and grouping scopes
• Authorization Code Failure Notifier for surfacing authorization failures

Applications are not required to implement their own token service to use Blazorade ID.

Advanced scenarios may replace the Token Service to customize token acquisition behavior, caching strategies, or identity provider integration. Custom implementations are expected to follow the same behavioral contract, including respect for prompt options, failure notification, and authentication state updates.

• OAuth 2.0 Authorization Framework (RFC 6749): https://datatracker.ietf.org/doc/html/rfc6749
• OAuth 2.0 Authorization Code Grant with PKCE (RFC 7636): https://datatracker.ietf.org/doc/html/rfc7636
• OpenID Connect Core 1.0: https://openid.net/specs/openid-connect-core-1_0.html
• Microsoft identity platform documentation – Tokens: https://learn.microsoft.com/entra/identity-platform/access-tokens