Authentication Flows
A high-level overview of how authentication flows work with a native mobile or desktop app.
Overview
This guide explains how user login and logout flows work when integrating Wristband with a native application. In this integration pattern, your native application initiates authentication through a system browser, securely stores authentication tokens on the device, and maintains the user's authenticated state locally.
Login Flow
The login flow uses the OIDC Authorization Code Flow with PKCE to authenticate users through Wristband. Your native application initiates the authentication request in a system browser, exchanges the resulting authorization code for tokens, and establishes the user's authenticated state locally.
The following steps describe the login process:
-
User Initiates Login: The user taps the Login button in your native application.
-
Native Application Initiates Authentication: The application generates a PKCE code verifier and code challenge, then opens a system browser to navigate to Wristband's Authorize Endpoint. The authorization request includes the necessary parameters, such as the client ID, redirect URI, requested scopes, and PKCE code challenge. The application temporarily retains the code verifier for use when exchanging the authorization code.
-
Wristband Processes the Authorization Request: Wristband validates the request and directs the user to either the application-level hosted login page (if no tenant was specified) or the tenant's hosted login page (if a tenant was specified). If the user already has a valid Wristband authentication session, Wristband may automatically authenticate them without requiring them to log in again.
-
User Authenticates: The user completes authentication through the Wristband-hosted login page. Upon successful authentication, Wristband establishes an authentication session associated with the tenant's vanity domain.
-
Wristband Redirects to the Native Application: Wristband redirects the browser to the application's registered redirect URI, including an authorization code. The native application receives this redirect using a supported deep-linking mechanism, such as Universal Links, App Links, or a custom URI scheme.
-
Native Application Exchanges the Authorization Code: The application's Callback Handler validates the authorization response and calls Wristband's Token Endpoint to exchange the authorization code for tokens using the original PKCE code verifier. The response includes an access token and an ID token. If the original authorization request included the
offline_accessscope, a refresh token is also returned. -
Native Application Retrieves User Information: The application calls Wristband's UserInfo Endpoint using the access token to retrieve claims about the authenticated user. The claims returned depend on the scopes requested in the authorization request.
-
Native Application Establishes Authenticated State: The application securely stores the authentication information needed to maintain the user's authenticated state, such as the access token, refresh token (if issued), token expiration time, and relevant user and tenant information. Sensitive tokens persisted on the device should use platform-provided secure storage mechanisms.
-
User Returns to the Application: The application navigates the user to its authenticated home screen or originally requested destination. The user can now access protected resources within the application.

Figure 1: Native application login flow using the OIDC Authorization Code Flow with PKCE.
Native Application State vs. Wristband Authentication Session
Although both are established during login, the native application's authenticated state and the Wristband authentication session operate independently.
The Wristband authentication session is maintained through cookies in the system browser and enables automatic reauthentication with Wristband. The native application's authenticated state is maintained locally using securely stored tokens and user information.
Your native application can use the access token to make authenticated API requests on behalf of the user. If the access token expires, the application can use the refresh token, when available, to obtain a new access token without requiring the user to log in again.
Logout Flow
When a user logs out, your native application must clear its locally stored authentication state and terminate the Wristband authentication session. If a refresh token was issued during login, it should also be revoked to prevent further token refreshes.
The following steps describe the logout process:
-
User Initiates Logout: The user taps the Logout button in your native application.
-
Native Application Clears Authentication State: The application deletes locally stored authentication tokens and clears the user's authenticated state. This prevents the application from continuing to use the locally stored credentials to access protected resources.
-
Native Application Revokes the Refresh Token: If a refresh token was issued, the application calls Wristband's Revoke Token Endpoint to invalidate it. This prevents the refresh token from being used to obtain new access tokens.
-
Native Application Opens Wristband Logout: The application opens Wristband's Logout Endpoint in the system browser using the tenant's vanity domain. This ensures that the browser includes the appropriate Wristband authentication session cookie in the request.
-
Wristband Terminates the Authentication Session: Wristband invalidates the user's authentication session and clears the associated session cookie. This prevents Wristband from automatically reauthenticating the user using the terminated session.
-
User Returns to the Application: Wristband redirects the browser to the configured redirect URL. When this URL is registered to open the native application, the user is returned to the application's logged-out or login screen, completing the logout flow.

Figure 2: Native application logout flow, including local authentication state cleanup, refresh token revocation, and termination of the Wristband authentication session.
Why Both Authentication States Must Be Cleared
Clearing the native application's locally stored tokens does not automatically terminate the user's Wristband authentication session.
If the Wristband authentication session remains valid in the system browser, the user may be automatically reauthenticated the next time they initiate login, without needing to enter their credentials.
Updated 16 days ago