Hub Summary

The Hub Summary service provides a way to retrieve a summary of unviewed tokens for user accounts. Its primary purpose is to enable applications to display notification badges or summaries showing how many new tokens are available for users to view.

Prerequisites

Before accessing the Unviewed Tokens Service, ensure you have:

• Partner-level Session Token: Obtained by following Authentication. This token is required to authenticate API requests.
• External User ID: Your system's identifier for the user.
• External Program ID: Your system's identifier for the program that maps to a specific Kigo program configuration. Contact your Kigo integration team member if you need assistance identifying this value.

Steps to Implement

1. Look Up the Account ID

• Purpose: Convert your external identifiers into a Kigo account ID.
• Endpoint Reference: Lookup account by external IDs
• Usage: Make a GET request with external_user_id and external_program_id query parameters.
• Response: A successful 200 OK response returns the account_id needed for the next step.

2. Retrieve the Hub Summary

• Purpose: Get the unviewed tokens count for the account.
• Endpoint Reference: Get account hub summary
• Usage: Make a GET request to /api/v1/accounts/{account_id}/hub-summary using the account_id from Step 1.
• Response: A successful 200 OK response contains unviewed_products count and total_tokens for the account.

Example Workflow

Scenario: A mobile app needs to show a notification badge indicating how many unviewed tokens a user has.

sequenceDiagram
    participant App as Mobile App
    participant Backend as Your Backend Server
    participant Kigo as Kigo API

    App->>Backend: GET /api/user/unviewed-count
    Note over Backend: Check token cache
    Backend->>Kigo: POST /api/v1/auth/sessions<br/>{partner_id, api_key}
    Kigo-->>Backend: {token}
    Note over Backend: Cache token (30 min)

    Backend->>Kigo: GET /api/v1/accounts<br/>?external_user_id=user123<br/>&external_program_id=program456
    Kigo-->>Backend: {account_id, ...}

    Backend->>Kigo: GET /api/v1/accounts/{account_id}/hub-summary
    Kigo-->>Backend: {unviewed_products: 12, ...}

    Backend-->>App: {count: 12}
    Note over App: Display badge with count

1. Client Request: Mobile app makes a request to YOUR backend server endpoint (e.g., /api/user/unviewed-count).
2. Authenticate: Your backend obtains a partner-level session token from Kigo (cache for up to 30 minutes).
3. Lookup Account: Your backend calls Kigo to get the account ID.
4. Get Hub Summary: Your backend retrieves the hub summary using the account ID.
5. Return to Client: Your backend extracts the unviewed_products count and returns it to the mobile app.
6. Display Badge: The mobile app displays the count in a notification badge.

Best Practices

• Server-Side Only: All API calls in this guide must originate from your secure backend server. Never expose your API Key or Partner ID to client-side code (browsers, mobile apps). The authentication endpoint contains sensitive credentials and must only be called server-side.
• Cache Tokens: Store partner-level session tokens in your backend cache (Redis, Memcached, etc.) to avoid re-authenticating for every request.
• Cache Hub Summary Data: Consider caching hub summary responses for a short duration (e.g., 5-15 minutes) to reduce API calls while keeping data reasonably fresh.
• Implement Retry Logic: For transient errors (500 Internal Server Error), implement automatic retry with exponential backoff.
• Validate External IDs: Verify that external user IDs and program IDs exist in your system before making API calls.
• Monitor API Usage: Track API response times and error rates to identify issues early.
• Secure Credential Storage: Store API keys and partner IDs in environment variables or secure vaults (AWS Secrets Manager, Azure Key Vault, etc.).