Authentication

Authorization is essential for ensuring that only authenticated users can interact with your application and access secure features. This section outlines how the Kigo Loyalty Wallet Web SDK manages user session tokens and provides guidance on handling authorization in your application.

Overview of the Authorization Process

The Kigo Loyalty Wallet Web SDK requires a Session Token to authenticate individual user sessions within your application. This token ensures that only authorized users can perform actions such as claiming rewards, accessing their wallet, or sharing tokens.

Important Note:

• API Account Token: The SDK does not manage the API account token directly. It is your backend's responsibility to handle the API account token, maintain the account session, and generate the user session token. The generated session token should then be provided to the SDK to enable its functionality. Refer to the API Authentication page for more details.

Key Methods and Callbacks

1. setAuthorizationToken(token: string)

• Purpose: Sets the session token used to authenticate the user's session within the SDK. This token is stored securely in sessionStorage under the key kigo-auth-token and is used for all subsequent API requests made by the SDK.
• Example Usage:
  JavaScript

  Kigo.setAuthorizationToken("your-session-token");
  

• When to Use: This method should be called after successfully generating a session token on your backend, typically during the user login process.

2. onAuthorizationError(error: unknown | Error)

• Purpose: A callback function that is triggered when an authorization error occurs, such as when a session token is missing, expired, or invalid. This callback allows you to handle re-authentication or token renewal seamlessly.
• Example Usage:
  JavaScript

  Kigo.onAuthorizationError = function (error) {
    console.error("Authorization error:", error);
    // Implement re-authentication or token renewal logic here
  };
  

• When to Use: Use this callback to catch and manage any issues related to user authentication, ensuring a smooth user experience even when authorization issues arise.

3. Handling Token Expiry

If a session token expires, the SDK will automatically trigger the onAuthorizationError callback. It is recommended that you implement logic in this callback to:

• Prompt the user to log in again if the token cannot be refreshed.
• Request a new session token from your backend if a new token is available.

4. Re-authentication Flow

In cases where re-authentication is required, you can use the onAuthorizationError callback to redirect users to a login screen or display a modal asking them to re-authenticate. After obtaining a new session token, use the setAuthorizationToken method to update the SDK with the new token, allowing the user to continue their session without interruption.

Best Practices

• Backend Token Management: Ensure that your backend securely handles the API account token and is responsible for generating the user session token before passing it to the SDK.
• Handle Errors Gracefully: Use the onAuthorizationError callback to provide a smooth user experience, even when authorization issues occur.
• Secure Storage: The session token is stored in sessionStorage under the key kigo-auth-token. Make sure to handle this token securely to prevent unauthorized access.

Summary

The Kigo Loyalty Wallet Web SDK relies on a user session token for authentication, which must be provided by your backend after securely handling the API account token. By utilizing setAuthorizationToken and handling onAuthorizationError appropriately, you can ensure a secure and seamless experience for your users.

For more technical details on generating user session tokens, refer to the API Getting Started Page for more details.