Personalized catalogs

B2B product catalogs tend to be complex, with many product variations and specific terms and conditions for each buyer account. Often, the B2B purchasing process is also more complex, involving different users with different permissions. With Algolia, you can use secured API keys to ensure each signed-in user can search or browse only the part of the product catalog they’re entitled to access.

Entitlement policies

Sellers often create a public product catalog for all users that aren’t signed in. For each buyer, sellers can create a custom product catalog visible only for signed-in users associated with the buyer account. In B2B the main buyer entity is a company account, that can have many user accounts with different access permissions, depending on their roles and responsibilities in the purchasing process. An administrator role would have full permissions. A company account’s administrator would then define further roles with permissions according to the unique requirements of the company. For example, a buyer role could have access to all Sales and Quotes resources, were a view-only role would be able to browse the custom product catalog and view orders, quotes, and other information, but not place orders.

Your search and browse strategy needs to respect:

• Per-account entitlement policies. Each signed-in user can only search and browse the custom product catalog according to their company account. Thy should only see the products and conditions defined between the buyer and seller, such as variants, bundles, minimum order quantity, pricing, and more.

• User-level entitlement policies. Each signed-in user can only search, browse, and interact with the product catalog according to their roles and permissions, as defined by the buyer account’s administrator.

What are secured API keys?

When searching in an Algolia index, you need to send an API key with your search request to authenticate with Algolia. With your Search-only API key, users can search the full product catalog. From this key, you can derive secured API keys with more restricted scopes.

For example, you can use secured API keys to:

• Restrict the search to a specific index
• Apply predefined filters to every search
• Apply predefined search parameters to every search

When you apply search parameters and filters when creating secured API keys, users can’t override or remove them at search time.

Accessing personalized product catalogs with secured API keys

At a high level, using secured API keys has two steps:

1. When users start searching, your client-side app or website requests a secured API key from your server. Your server creates a secured API key with a pre-applied filter and returns it to the client.
2. Your client-side app uses the secured API key for searching.

Implementing secured API keys

To implement secured API keys, follow these steps:

1. Prepare your index. Add an attribute to each record that signals who has access to this record.

   JSON

   Copy

   1
   2
   3
   4
   5
   {
     "objectId": "product-123",
     "visible_by": ["company-1", "company-3"]
     // Other attributes
   }
   

   In this example, this record should only show for users from company 1 or company 3, but not for other users.

2. Create a secured API key on your backend. To prevent exposing the search API key, you need to create the secured API key on your backend. Otherwise, users can override the restrictions built into the secured API key and access the whole product catalog.

   To create a secured API key with the JavaScript API client:

   JavaScript

   Copy

   1
   2
   3
   const publicKey = client.generateSecuredApiKey('SEARCH_API_KEY', {
     filters: `visible_by: ${groupID}`,
   })
   

   This binds the filter to the API key which can’t be changed at search time. To apply this filter, your search backend needs to get the group membership of the signed-in user from your ecommerce platform.

3. Communicate the API key to the frontend. Your frontend can request the secured API key from the backend:

   JavaScript

   Copy

   1
   2
   3
   4
   5
   6
   function getPublicKey() {
     const apiKey = fetch('BACKEND-URL/api-key')
       .then((response) => response.json())
       .then((data) => data.apiKey)
     return apiKey
   }
   

   On your backend, you need to create a corresponding API resource, for example, using express:

   JavaScript

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   const express = require("express");
   const app = express();
   
   app.get('/api-key', (_, res) => {
     const publicKey = client.generateSecuredApiKey("SEARCH_API_KEY", {
       filters: `visible_by: ${groupID}`
     });
   
     res.send({ apiKey: publicKey });
   })
   

   If your front and back ends are on the same server, you can also inline the API key.

When searching, your frontend uses the secured API key:

1
2
3
4
5
getPublicKey().then(publicKey => {
  const searchClient = algoliasearch("APP_ID", publicKey);
  const search = instantsearch("INDEX_NAME", searchClient);
  // ...
});

The results only show records where the group ID of the current user matches the visible_by attribute.