User Client Level Authentication

The Kigo API employs multiple levels of session tokens. To interact with the user-level endpoints in the Kigo API, a partner must authenticate requests using user-level session tokens. The user-level session token is used by all of the all of the endpoints in the Kigo Loyalty Wallet API and by the Kigo Loyalty Wallet Web SDK. Below, this guide will describe the details of how to obtain a user-level token, how to use the token in requests, and important considerations regarding token expiration and renewal.

Prerequisites

Before making an API call to create a user-level session token, obtain a partner-level session token following the API Authentication Guide.

Steps to Implement

Once a partner has a partner-level session token, they can create a user-level session token, which is necessary for making API requests that are specific to an individual user.

Creating a User-Level Session Token
- Endpoint: Creates an API session token for a user account.
- Purpose: This token is used to authenticate requests that involve specific user actions or data.
- Token Expiration: The user-level session token is also valid for 30 minutes. Ensure the application handles token renewal as needed.
Using the User-Level Session Token
- Header Example:
```
Authorization: Bearer user-level-session-token
```

Key Considerations

Handling Token Expiration: User-level session tokens expire after 30 minutes. To maintain uninterrupted access to the API:
- Token Renewal: Before a token expires, generate a new one using the same process as initially obtaining it. Automating this process in the application can help avoid any disruption.
- Error Handling: If a token expires and an API call is made with it, the API will return an authentication error. The application should handle this error gracefully, possibly by automatically requesting a new token and retrying the request.

Example Workflow

Start by obtaining an partner-level session token using the guide at API Authentication Guide.
Use this token to create a user-level session token for the specific user the application needs to interact with.
Include the user-level token in API requests to authenticate and access user-specific resources.
Monitor token expiration and renew tokens as needed to ensure continuous API access.

Best Practices for Authorization

HTTPS Only: Always make API requests over HTTPS to ensure that tokens and other sensitive data are encrypted in transit.
Pass to the Client: User-level tokens are safe to pass to clients and do not need to remain in controlled environments. This is because they are scoped to user-level access. They are intended to be used after a user passes an authentication method in the application and proves they are authorized to access their Kigo-powered wallet.