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:
- Bolt sends an authorization code to an endpoint in your system from the shopper’s browser.
- Your system sends a
POST
request to Bolt, using the authorization code provided. - Bolt sends your system an ID token containing:
- ✓ Shopper’s
External ID
- ✓ Shopper’s Bolt Account
Email Address
- ✓ Shopper’s
- 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.
- If logged in, your system then redirects the shopper to the My Account page.
How to Integrate with SSO Commerce
WARNING
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. Export Accounts
You must export your existing shopper accounts in the following xml
format:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Customers">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="Customer">
<xs:complexType>
<xs:sequence>
<xs:element name="Customer_ID" type="xs:string" />
<xs:element name="First_Name" type="xs:string" />
<xs:element name="Last_Name" type="xs:string" />
<xs:element name="Email" type="xs:string" />
<xs:element name="Phone" type="xs:string" />
<xs:element name="Date_Joined" type="xs:string" />
<xs:element name="Addresses">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="Item">
<xs:complexType>
<xs:sequence>
<xs:element name="Address_First_Name" type="xs:string" />
<xs:element name="Address_Last_Name" type="xs:string" />
<xs:element name="Address_Line_1" type="xs:string" />
<xs:element name="Address_Line_2" type="xs:string" />
<xs:element name="City" type="xs:string" />
<xs:element name="State" type="xs:string" />
<xs:element name="Zip" type="xs:string" />
<xs:element name="Country_Code" type="xs:string" />
<xs:element name="Address_Phone" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Important
Date_Joined
must be provided in RFC 3339 format (e.g.2021-08-15T19:16:21.0Z
).Country_Code
must be a two-letter country code as indicated by ISO 3166-1’s alpha-2 codes.
Example
2. Import Accounts
Reach out to Bolt for assistance with uploading your exported accounts.
3. 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> |
4. Install Login/Register Button
The following steps must be completed on every page where shoppers can log in or register an account.
- Add a div element with the class name
bolt-account-sso
.<div class="bolt-account-sso" />
- 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://connect.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>
TIP
Custom Buttons: To create your own button with custom styling, 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.
5. Build Endpoints
Refer to the Merchant Callback API spec for schema information, authentication, and query parameters.
Build a Get Account Endpoint
Bolt needs to be able to check your store system for the existence of a preexisting shopper account on your store. Using that information, Bolt can proceed with linking a store account and bolt account appropriately,
Bolt calls your Get Account endpoint when checking for the account status. This endpoint should accept POST
requests that are signed with Bolt’s Signing Secret and contain the shopper’s email address.
Request
{ email: <the email address> }
Response
- Success:
200 HTTP OK
- Failure:
404 Not Found
Build an OAuth Login Endpoint
Bolt uses OAuth to authorize your store to access Bolt Account data for a specific shopper. Bolt calls your OAuth Login endpoint with an authorization grant that will allow you to perform an OAuth Token exchange on your store backend. This process informs you to log the shopper into their corresponding store account. This endpoint should accept GET
requests that contain all of the following query parameters:
- Authorization Code
- State
- Scope
- Order ID (optional)
Request with Query Parameters
https://website.com/bolt-login?code=A&state=B&scope=C&order\_id=D
What should the OAuth Login Endpoint do?
- Validate the query params passed to the endpoint.
- State: must be an 8 character
string
. - Scope: must include
openid
.
- State: must be an 8 character
- Exchange the authorization code for an ID token with Bolt’s
/v1/oauth/token
endpoint. - Fetch Bolt’s RSA public key:
- Fetch Bolt’s Open ID configuration from the following endpoints exposed Bolt.
- Sandbox:
https://api-sandbox.bolt.com/.well-known/openid-configuration
- Production:
https://api.bolt.com/.well-known/openid-configuration
- Fetch Bolt’s RSA public key from the
jwks_uri
indicated in the Open ID configuration.
- Parse and validate the ID token using Bolt’s RSA public key.
- You can use any standard JWT validation library to do this.
- 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.
- If Email Recognized & Bolt Verified: Create a new account, log the shopper in, and record the
- Link the Order ID, if provided, to the logged-in account.