📍 Bolt / Developers / Developer Guides / Checkout Setup / Custom API Checkout / Set Up SSO Commerce For Custom API Integrations
👎

Set Up SSO Commerce For Custom API Integrations

Use this guide to set up Bolt’s SSO Commerce on your Custom Cart store.

Login Workflow

When a shopper selects your Login or Register button, the Bolt modal is displayed for them to input their account credentials. This triggers the following series of actions:

  1. Bolt sends an authorization code to an endpoint in your system from the shopper’s browser.
  2. Your system sends a POST request to Bolt, using the authorization code provided.
  3. Bolt sends your system an ID token containing:
    • ✓ Shopper’s External ID
    • ✓ Shopper’s Bolt Account Email Address
  4. Your system then must make one of the following decisions:
    • ID is recognized: Log the shopper into your store.
    • ID not recognized: Create a new account, log the shopper in, and record the ID.
    • Email Recognized & Verified: Log the shopper in and record the ID.
    • Email Recognized & Not Verified: Throw an error.
  5. If logged in, your system then redirects the shopper to the My Account page.

How to Integrate with SSO Commerce

You must validate the ID Token and the Signing Secrets used in all of your interactions with Bolt. See Environment Details for a full list of keys and URLs.

1. Create Database Table

You must create a new database table used to link external IDs Bolt provides with the accounts found in your existing account management system. This table is updated in Step 4 of the Login Workflow.

Example External_Account Database Table
External Ids (Bolt) Internal Ids
<external-bolt-id#1> <internal-id#1>

2. Install Login/Register Button

The following steps must be completed on every page where shoppers can log in or register an account.

  1. Add a div element with the class name bolt-account-sso.
    <div class="bolt-account-sso" />
    
  2. Add the following account.js script:
    <script>
         var insertAccountScript = function () {
             var scriptTag = document.getElementById('bolt-account');
             if (scriptTag) {
                 return;
             }
             scriptTag = document.createElement('script');
             scriptTag.setAttribute('type', 'text/javascript');
             scriptTag.setAttribute('async', '');
             scriptTag.setAttribute('src', 'https://account.bolt.com/account.js');
             scriptTag.setAttribute('id', 'bolt-account');
             scriptTag.setAttribute('data-publishable-key', <insert publishable key>);
             document.head.appendChild(scriptTag);
         }
         function insertButtons() {
             if (typeof BoltAccount === 'undefined') {
                 window.setTimeout(insertButtons, 100);
                 return;
             }
             BoltAccount.injectButtons();
         }
         insertAccountScript();
         insertButtons();
     </script>
    

Custom Buttons: To create your own button with custom styling, simply add the bolt-sso-custom class to your element. This enables the account.js script to inject an onClick event, which opens Bolt’s login/registration modal.

3. Build Endpoints

Refer to the Merchant API spec for schema information, authentication, and query parameters.

GetAccount Endpoint

Bolt calls your /api-merchant/#operation/account.get endpoint when checking for a shopper’s account. This endpoint should accept POST requests that are signed with Bolt’s Signing Secret and contain the shopper’s email address.

Example JSON Request
{ email: <the email address> }
  • Success: HTTP OK
  • Failure: 404 Not Found

Build an OAuth Login Endpoint

Bolt calls your /oauth/login endpoint when attempting to log a shopper into your system. This endpoint should accept GET requests that contain all of the following query parameters:

  • Authorization Code
  • State
  • Scope
  • Order ID (optional)
Example URL with Parameters
https://website.com/bolt-login?code=A&state=B&scope=C&order\_id=D

How to Handle the Request

  1. Validate the query params.
    • State: must be an 8 character string.
    • Scope: must be openid.
  2. Exchange the authorization code for an ID token with Bolt’s /oauth/token endpoint.
  3. Parse and validate the ID token using your Public Key.
  4. Use the ID token to determine if an account already exists for the shopper.
    • ID is recognized: Log the shopper into your store.
    • ID not recognized:
      • If Email Recognized & Bolt Verified: Create a new account, log the shopper in, and record the external-id by creating a new entry in the External_Account table.
      • If Email Recognized & Not Bolt Verified: Throw an error.
  5. Link the Order ID, if provided, to the logged-in account.
📖 On This Page