Integrating Session Management in your application

In this workflow, the session management is handled by the merchant’s server, which communicates with the OTPLESS server to ensure that the user’s session is valid. This is the most secure and scalable method, as it centralizes session management at the server level.

Here’s a flowchart showcasing how session management and authentication with OTPLESS work together:

Summary of the flowchart:

1. User Authentication: When the user successfully authenticates via OTPLESS SDK on the merchant’s application, the merchant receives a sessionToken and a refreshToken from OTPLESS. The sessionToken is meant for the frontend and should be securely stored in the application’s local storage, while the refreshToken is intended for the backend and should be stored securely on the server.

2. Action Trigger: When the user performs an action that requires session validation, the merchant’s frontend sends the sessionToken to merchant’s server, which then forwards the sessionToken provided by OTPLESS during user authentication for validation to OTPLESS server.

3. OTPLESS Server Validation: The OTPLESS server checks the validity of the sessionToken and responds to the merchant server with a validation result:

   • If valid: The action proceeds smoothly, indicating the user’s session is valid and the user can proceed with the action they wanted to perform.
   • If invalid: The merchant server proceeds to the next step by sending the refreshToken to OTPLESS to validate the refreshToken and create a new sessionToken.

4. Refresh Token Validation: The OTPLESS server validates the refreshToken to determine if it is still valid:

   • If valid: OTPLESS generates a new sessionToken, which is returned to the merchant server. The merchant server updates the previously issues sessionToken with the newly issued sessionToken.
   • If invalid: The user’s session is terminated, and they are required to authenticate again.

Key Terms

• sessionToken: A temporary JWT (JSON Web Token) key that allows the user to stay logged in without re-authenticating each time. It has a short expiry time.
• refreshToken: A backup JWT (JSON Web Token) key used to request a new sessionToken when the current one expires, keeping the user logged in. It has a long expiry time, typically the time for which you want the user to be kept logged in.

This method ensures that the session management process is both secure and resilient, leveraging centralized validation at the backend level.

Integration & Setup

Initial setup

1. Configure OTPLESS dashboard: In Session Management section, enable Session Management and set the parameters as per your choice. Click the save button once session management is enabled and its parameters are set.
2. Get OTPLESS credentials: Get the OTPLESS credentials from dashboard. Store them securely for using them in session management.
3. Integrate OTPLESS on your application: Users must be authenticated via Otpless SDK to implement session management. To integrate Otpless SDK on your application, follow this guide.

Workflow

1. Once the user successfully logs in via OTPLESS SDK on your application, securely store sessionToken and refreshToken provided by OTPLESS at your preferred location.
2. To perform any session related logic such as validation, renewal, or revocation of a user’s session, follow the below mentioned API endpoints.

API Endpoints

These are the API endpoints that OTPLESS provided to seamlessly integrate Session Management in your application.

1. Validate Session (v1/sessions/validate-session): Validates an existing user session using sessionToken issued by OTPLESS.

   • This API should be used whenever user performs an action on merchant app/website that requires their session to be valid.
   • Example: A user is navigating the merchant’s app or website and tries to access a feature like viewing order history or account settings. Before allowing access, the app checks if their session is still valid by using this endpoint. If the session is invalid, the user may need to **create a new sessionToken.

2. Create New Session Token (v1/sessions/get-new-session-token): Creates a new sessionToken using the refreshToken if the refreshToken is still valid.

   • This API should be used when the Validate Session API responds that the session is not valid. It returns a new sessionToken if the refreshToken is valid.
   • Example: A user’s session expires while they are still actively using the app. Instead of forcing the user to log in again, the app uses this endpoint to generate a new sessionToken using the existing refreshToken, ensuring uninterrupted access.

3. Get Session Details (v1/sessions/get-session-details): Retrieves detailed information related to the user’s session, such as user phone number and network details.

   • This API should be used when the merchant wants to fetch the user’s details associated with the corresponding sessionToken.
   • Example: A merchant wants to personalize the user’s experience by displaying their name or phone number in the app. By calling this endpoint, the app can retrieve the session details associated with the sessionToken, such as the user’s phone number or email id, whichever the user has provided for authentication.

4. Revoke Session (v1/sessions/revoke-session): Revokes a user’s session, typically called upon logout.

   • This API should be used when the merchant wants to terminate the user’s session. This API will revoke the corresponding sessionToken and refreshToken.
   • Example: A user logs out of the app, either manually or due to inactivity or there may have been suspicious activity on user’s device, due to which merchant may want to re-authenticate the user. This endpoint is used to securely terminate the user’s session, ensuring that their sessionToken can no longer be used for validation and a new sessionToken cannot be created using the refreshToken.