Reveal Tokens

The Kigo API allows users to reveal certain tokens, such as bundles or hidden tokens, to access their full details or contents. This action is essential for tokens that initially conceal their content or for bundles that contain multiple tokens.

Prerequisites

Before performing the reveal action on a token, ensure that the necessary user-level session token has been obtained. This token is required to authenticate API requests and can be acquired by following the User Client Level Authentication.

Steps to Implement

1. Revealing a Token

   • Purpose: The reveal action uncovers the contents or details of a token that is initially hidden or bundled. This is commonly used for bundle tokens that contain multiple child tokens or for tokens like gift cards that start in a hidden state.
   • Usage: The application should only present the reveal option if the token can be revealed, as indicated by the flags.is_revealable property in the Get Token By ID response.

2. Determining If a Token Can Be Revealed

   • flags.is_revealable Property: The ability to reveal a token is determined by the flags.is_revealable property in the Get Token By ID response. If this property is set to true, the token is eligible to be revealed. If it is false, the token cannot be revealed, and the reveal option should not be presented to the user.

3. Handling Revealed Tokens and Child Tokens

   • Content Access: Once a token is revealed, its full details or contents become accessible in the user’s wallet. For example:
     • Bundle Tokens: When a bundle token is revealed, the child_tokens contained within the bundle are uncovered. These child tokens are now available as individual tokens within the user's wallet.
   • Accessing Child Tokens:
     • Get Token by ID: After revealing a bundle token, the individual child_tokens can be accessed by calling the Get Token by ID API endpoint. This will return the details of the revealed bundle along with its associated child tokens.
     • Gallery Endpoint: Alternatively, users can retrieve a list of all their tokens, including any newly revealed child tokens, by using the Gallery API endpoint. Users can also filter for is_new tokens in this call to see a list of recently revealed tokens.

API Call

To reveal a token, use the API endpoint associated with revealing tokens. Refer to Reveal Tokens for specific details on the API request and response structure.

Key Considerations

1. Reveal Timing: Ensure that the reveal option is only available when the token is ready to be revealed. This is controlled by the flags.is_revealable property.
2. Child Token Access: Once a bundle token is revealed, its child_tokens can be accessed either by calling the Get Token by ID API or by retrieving the updated list of tokens through the Gallery API endpoint. Additionally, the is_new filter can be applied to the gallery endpoint to view recently revealed tokens.

Example Workflow

1. User decides to reveal a token: The user selects a token from their wallet that is marked as revealable.
2. The application checks the token’s flags.is_revealable property: The application checks this property in the Get Token By ID response to determine if the token can be revealed.
3. The token is revealed: The application makes the Reveal a token. API call. The contents or details of the token are then displayed in the user’s wallet.
   • For Bundle Tokens: The child tokens are displayed individually.
   • For Hidden Tokens: The previously hidden details, like gift card value, are revealed.
4. Accessing Child Tokens:
   • The application can retrieve the individual child tokens by calling the Get Token by ID API endpoint.
   • Alternatively, the user can view all their tokens, including the newly revealed child tokens, by using the Get the gallery of tokens belonging to a user account.endpoint and filtering for is_new tokens to see the most recently revealed tokens.