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 TOP SDK manages user session tokens and provides guidance on handling authorization in your application.

Overview of the Authorization Process

The Kigo TOP SDK requires a user session token to authenticate individual user sessions within your application. This token ensures that only authorized users can perform actions such as redeeming offers, accessing their wallet, or sharing tokenized offers.

Tokens are created by your backend in two steps:

1. Partner session token: POST /api/v1/auth/sessions with your partner_id and api_key. Valid for 1 hour. Keep this token and your API key on your server; never send them to the browser. See API Authentication.
2. User session token: POST /api/v1/auth/sessions/accounts, authorized with the partner session token. Returns a token (valid for 1 hour) and a refresh_token (valid for 365 days). Pass the token to the SDK. See User Client Level Authentication.

To renew a user session without repeating step 2, your backend can exchange the refresh_token at POST /api/v1/auth/sessions/accounts/refresh for a new token and refresh_token.

Key Methods and Callbacks

1. setAuthorizationToken(token: string)

• Purpose: Sets the user session token for the SDK. The token is stored in sessionStorage under the key kigo-auth-token and sent as a Bearer token on all subsequent API requests made by the SDK.
• Example Usage:
  JavaScript

  window.Kigo.onReady = function (kigo) {
    kigo.setAuthorizationToken('your-session-token');
  };

• When to Use: Call this after your backend creates a user session token, typically during the user login process, and again whenever you obtain a new token.

2. refreshAuthorizationToken(): Promise<string>

• Purpose: An optional callback you provide. Before each API request, the SDK checks the stored token's expiry. If it has expired, the SDK calls refreshAuthorizationToken, stores the token you return, and continues the request with it.
• Example Usage:
  JavaScript

  kigo.refreshAuthorizationToken = async function () {
    const response = await fetch('/api/your-backend-endpoint', { method: 'POST' });
    const data = await response.json();
    return data.token; // new user session token
  };

• If not provided (or it fails): The SDK waits up to 5 seconds for you to call setAuthorizationToken with a valid token before sending the request.

3. onAuthorizationError(error: unknown)

• Purpose: An optional callback that is triggered when an SDK API request returns 401 Unauthorized, for example when the token is missing, invalid, or has been revoked.
• Example Usage:
  JavaScript

  kigo.onAuthorizationError = function (error) {
    console.error('Authorization error:', error);
    // Re-authenticate the user or request a new token, then call kigo.setAuthorizationToken(newToken)
  };

• When to Use: Use this callback to recover from authorization failures, for example by requesting a new token from your backend or sending the user back through your login flow.

4. Re-authentication Flow

1. Your backend creates a new user session token (or refreshes it with the refresh_token).
2. Your application returns the new token from refreshAuthorizationToken, or calls setAuthorizationToken with it.
3. The SDK uses the new token for subsequent requests, and the user continues without interruption.

If a new token cannot be obtained, redirect the user to your login screen or display a modal asking them to sign in again.

Best Practices

• Backend Token Management: Your backend handles your API key and the partner session token, and creates the user session token before passing it to the SDK.
• Renew Before Expiry: User session tokens are valid for 1 hour. Provide refreshAuthorizationToken so the SDK can renew tokens without interrupting the user.
• Handle Errors Gracefully: Use onAuthorizationError to provide a smooth user experience when authorization issues occur.
• Secure Storage: The user session token is stored in sessionStorage under the key kigo-auth-token. Treat it as a credential for that user.

Summary

The Kigo TOP Web SDK relies on a user session token for authentication, which your backend creates after authenticating with your partner credentials. Use setAuthorizationToken to provide the token, refreshAuthorizationToken to renew it when it expires, and onAuthorizationError to recover from 401 errors.

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