Migrate to the Hosted Customers Solution

📘

Who is this Guide for?

The information reported in this page is useful only to Clients that have already integrated with Bud in one of our production environments using the old Customer Secret approach.

The new Hosted Customers solution is the new default behaviour in our architecture. It doesn't require the Client to store the Customer Secret on their side. If you started integrating after November 2023, you can ignore this Guide.

Please ensure to adopt this approach and contact us if you have any questions.

Assumptions

In this guide we assume the Client uses the Create Customers v1 or v2, but the same process can be followed if the Client already hits the v3 version of that endpoint. In the example we’ll use the Fetch Transactions endpoint, but the same concepts are valid for all the other endpoints in our offering.

Benefits of the Hosted Customers Solution

Faster and cheaper integration with the Bud Platform.

Bud can automate many customer data actions for you (such as refreshing connected account data).

Automatically get the latest and best versions of our machine learning models applied to your entire customer base.

Step 1 - Get in touch

The first step to start the Hosted Customer migration is to get in touch with us and let us know you are starting this process. We’ll enable your Organisation to start the migration and we’ll start capturing the X-Customer-Secret you send us as part of your standard flow.

From that moment on, every time you send Bud a request that includes the X-Customer-Id and the X-Customer-Secret headers, we’ll capture that secret and store it securely on our side.

It’s important you don’t stop sending us the X-Customer-Secret until all your active customers have been migrated over.

Step 2 - Change how you create new Customers

Migrate to the latest version of the Create Customer endpoint Create Customer V3. We have enabled the Hosted Customers feature as default, this means that if you don’t specify"host_secret": false in your request body, all customers created with this endpoint will be automatically hosted by Bud.

Request example:

curl --request POST  
     --url <https://api-sandbox.thisisbud.com/platform/v3/customers>  
     --header 'X-Client-Id: b5b72954-2dc8-444f-806e-2ee23bb25d8e'  
     --header 'accept: application/json'  
     --header 'authorization: Bearer XXXX'  
     --header 'content-type: application/json'

Response example:

{  
  "operation_id": "platform_v3_customers_post",  
  "data": {  
    "customer_id": "360e5821-4f18-4077-83f4-c9a7c1768bea",  
    "customer_context": {  
      "type": "personal",  
      "region": "GB",  
      "locale": "en-GB",  
      "host_secret": true,  
      "models": {  
        "categorisation": "uk-v2"  
      }  
    }  
  }  
}

Two things worth noting in the response:

• the host_secret is set to true, and this indicates that your customer is hosted by Bud
• in the response body there is nocustomer_secret attribute

After creating the customer, you’ll still need to store the customer_id in your storage linked to your user definition (as per the old integration), but you won’t need to store the secret.

All requests that will refer to this customer will now only require you to send the X-Customer-Id header. The X-Customer-Secret has been made optional on all the endpoints.

Step 3 - Change how you interact with the other Bud APIs

Most Bud’s APIs refer to a customer, and in order to interact with data linked to a specific customer we always require our Clients to send us the X-Customer-Id header as part of their request.

Historically, you were also required to send Bud the X-Customer-Secret, but after migrating to the Hosted Customers solution you no longer need to send us the customer secret header.

Example of a request before and after migrating to the Hosted Customers flow.

Before the migration:

curl --request GET  
     --url <https://api-sandbox.thisisbud.com/financial/v2/transactions>  
     --header 'X-Client-Id: b5b72954-2dc8-444f-806e-2ee23bb25d8e'  
     --header 'X-Customer-Id: c63878d4-7040-44b1-9631-f14051a1d359'  
     --header 'X-Customer-Secret: 60c45041389055ae87d54b1a8985d353d60dc77d6e0355deb068992c0c5fb7bf'  
     --header 'accept: application/json'  
     --header 'authorization: Bearer H67iYg4FZmmqoGDEK4H7q5hR4e3cfw8qP1UDxJcatJmxCbVTHGAXANiu6Ll7JrYvD6E6Q7dinpuDJ3RRUgJGfxPD6fbXp6Vp7TlR8mD0AXJlIaLvC1Hw7eW25hIpilbVBBhAv2O7puAW46rnqWIbo3HtfhsZFDUvwEzizjZkFk3koNsY8OHtCKHz7V1w4k1CMVl1Pa2Z8V47y2laOriVzn3GQqtgPC5koPmhiCUVWMyXsFXGjkhJup3R62K7Pt7'

After the migration:

curl --request GET  
     --url <https://api-sandbox.thisisbud.com/financial/v2/transactions>  
     --header 'X-Client-Id: b5b72954-2dc8-444f-806e-2ee23bb25d8e'  
     --header 'X-Customer-Id: c63878d4-7040-44b1-9631-f14051a1d359'  
     --header 'accept: application/json'  
     --header 'authorization: Bearer H67iYg4FZmmqoGDEK4H7q5hR4e3cfw8qP1UDxJcatJmxCbVTHGAXANiu6Ll7JrYvD6E6Q7dinpuDJ3RRUgJGfxPD6fbXp6Vp7TlR8mD0AXJlIaLvC1Hw7eW25hIpilbVBBhAv2O7puAW46rnqWIbo3HtfhsZFDUvwEzizjZkFk3koNsY8OHtCKHz7V1w4k1CMVl1Pa2Z8V47y2laOriVzn3GQqtgPC5koPmhiCUVWMyXsFXGjkhJup3R62K7Pt7'

The only difference is that after the migration the X-Customer-Secret is no longer needed. The responses of these two requests are identical.

🚧

Note

If the customer referenced in your request is Hosted by Bud, the request will still succeed even if you send us the X-Customer-Secret header (we will just ignore that secret).

However, if your customer is not Hosted by Bud and you don’t send the secret header, the request will fail.

These are all the changes needed on your code base to start using the Hosted Customers solution.

Identifying if a customer has been migrated to Hosted Customers

To help you understand if a Customer has been migrated or not, we introduced the new Retrieve Customer Context endpoint. Calling this endpoint with your Customer ID will give you all the information related to that customer, including a host_secret attribute that specifies if the customer is Hosted by Bud (host_secret=true).

You can use this information to decide if you should send the X-Customer-Secret header, or to check if all your customers have been migrated.

Note: We suggest you keep sending the X-Customer-Secret for all customers during the migration process, and remove it only when the migration is fully completed.

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.