Token Lifecycle and Integration

1 Sequence of Refresh Token operation
2 Integration Responsibilities – Fan App
- 2.1 During Login
- 2.2 On Token Expiration
- 2.3 On Logout
- 2.4 On Error Callbacks
- 2.5 Recommendation
- 2.6 Test Scenarios Checklist

This chapter describes the complete lifecycle of authentication tokens used within the TIXNGO SDK and outlines how to properly integrate token handling into the Fan App. It includes login, token renewal, offline fallback, logout scenarios, and the SDK’s internal mechanisms to ensure a seamless and secure user experience.

The TIXNGO SDK relies entirely on the Fan App’s existing authentication system using OpenID Connect (OIDC). The SDK does not manage authentication itself—it consumes tokens provided by the Fan App and handles access securely based on them.

In terms of user experience, it is critical that tickets remain accessible in these offline and degraded situations. As a result, the following rules must be enforced by both TIXNGO SDK and Fan App, by order of precedence:

Logout can be performed only if the device is online
Fan App can trigger logout of TIXNGO SDK only if:
1. User explicitly logout (while online)
2. IDToken expired, and IDP explicitly refused to refresh the token, while app is online
3. Fan App is offline more than lifetime of refresh token : ID token, access token and refresh token are expired. Fan App will logout user from the client side and send “logout” to SDK". As we are on offline mode, we are just discarding on-phone data; as a result tickets will disappear. Server-side, the device will still be considered as offline, with session opened as we do not provide active cleanup of expired session.
  Later, when the user attempts to open a new session (same device or new device), backend reads all sessions attached to the user, close any expired session, and evaluate applicable rules before allowing him to start a new session (by the creation of new device token).
SDK can initiate Fan App logout if
1. Force logout is initiated from TIXNGO backend

Sequence of Refresh Token operation

This diagram provides a comprehensive explanation of the sequence diagram for the token flow with TIXNGO SDK. It illustrates the interactions between the components during the token flow, including token acquisition, API calls, offline handling, and token renewal.

Host App: The main application initiating the login and handling tokens. (Fan App)
SDK: A software development kit embedded in the Host App, which makes API calls to the Backend. (TIXNGO SDK)
SSO: Single Sign-On service providing OAuth2 tokens. (Fan App using SSO)
Backend: The backend server providing API services. (TIXNGO Backend)

Detailed Flow Description

Login and Credential Acquisition
The Host App initiates a login request to the SSO service to obtain credentials (idToken, accessToken...).
The SSO service authenticates the request and returns the credentials (refresh token, access token, idToken) to Host App.
Credential Distribution and API Call
Host App pushes the idToken to the embedded SDK.
The TIXNGO SDK uses the tokens to call API generate the TIXNGO SecurityToken on Backend. (SecurityToken: Use to authorize the account on the TIXNGO Backend)
Backend processes the API request and sends back a response to the SDK.
Handling Token Expiration in Offline Mode
Condition: The idToken expires and the mobile device is offline.
Flow:
1. SDK attempts to call the API on Backend with the expired tokens.
2. Backend responds with a timeout.
3. SDK continues to function in offline mode.

Notes: The TIXNGO SDK still work in offline mode (cannot transfer, fetch tickets...)

4. Handling Token Expiration in Online Mode
Condition: The idToken expires and the mobile device is online.
Flow:

SDK attempts to call the API on Backend with the expired TIXNGO SecurityToken.

Backend responds with a 401 code - unauthorized error.

SDK calls, only once, a callback to Host App indicating that the JWT token has expired.

SDK will also try to stop other authenticated requests and wait for a new valid token.

Host App requests new credentials from the SSO service.

Happy case: The Host App can get new credentials from the SSO services
- The SSO service provides new credentials to Host App.
- Host App pushes the new idToken to the SDK.
- SDK call api to generate new SecurityToken from the new idToken
- SDK continues the API call to Backend with the new SecurityToken. All blocked calls will also detects the new token and retry.
- Backend processes the API request and sends back a response to the SDK.
Exception case: The Host App can not get new credentials from the SSO services (degraded situation)
- The SSO service fails to provide new credentials.
- Host App needs to return indication to TIXNGO SDK whether SSO explicitly refused (denial) or other type of failure.

instance.notifyTokenRenewalTransientIssue

(TokenRenewalIssueType reason);

enum TokenRenewalIssueType {

noInternet,

ssoUnspecifiedIssue

}

This will instruct TIXNGO SDK to continue to work with local storage (offline mode behavior) and preserve all data.

If case of explicit denial from SSO, Fan App will call sign-out and TIXNGO SDK will clear local storage.

This is flowchart & sequence diagram for API call in the SDK

Details:

The client makes an API request.
The API interceptor checks if the token is pending renewal.
- If yes, return an error.
- If no, add the token and send the request.
If the backend returns 401:
- Check if another request is already refreshing the token.
  - If yes, queue the request.
  - If no, call refreshToken() from the SSO service.
Once the new token is retrieved, process all queued requests.
Retry all requests with the new token and return responses to the user.

Integration Responsibilities – Fan App

To ensure secure and smooth integration of token lifecycle management, the Fan App must implement the following:

During Login

Authenticate via the OIDC provider
Retrieve and securely store:
- idToken
- refreshToken
Pass idToken to the SDK using its initialization method

On Token Expiration

Implement the SDK’s expiration callback listener
Use the refreshToken to retrieve new credentials
Push new valid idToken to the SDK
If refresh fails:
- On explicit denial → call SDK logout
- On transient error → instruct the SDK to enter offline mode

On Logout

When the user logs out of the Fan App, ensure:
- The SDK logout function is also called
- All tokens and caches are cleared appropriately

On Error Callbacks

Listen for error codes such as:
- 403: MAX_NUMBER_SECURITY_TOKEN
- 403: TOO_MANY_REGISTERED_DEVICES
Display appropriate messaging and take corrective action (e.g., device limit reached)

Recommendation

Invoke TixngoManager.shared.updateToken only in the following scenarios:
- After a successful login.
- Within the onInitialized(isAuthenticated: Bool) delegate when isAuthenticated is true.
- During the onJWTTokenExpired delegate.
If you intend to call updateToken when transitioning the app from background to foreground, ensure to check if the idToken has changed to avoid unnecessary calls to the SDK.

Test Scenarios Checklist

Utilize the scenarios below to verify that your integration with the TIXNGO SDK is operating correctly, specifically regarding authentication, token expiration recovery, and session/device limits: