📍 Bolt Help / Developer Resources / OAuth at Bolt
OAuth at Bolt
Learn about using Bolt OAuth to access Shopper API data.

Introduction to OAuth

OAuth 2.0 is the industry-standard protocol for providing authorization to third parties to act on behalf of a user (in this case a Bolt Shopper Account). Bolt leverages OAuth 2.0’s authorization code grant flow to grant access tokens and refresh tokens on behalf of Bolt Account users.

Bolt Shopper Account users will authenticate into Bolt and provide consent directly with Bolt to allow the third-party to access their account data. Once the user has successfully authorized the third-party on a Bolt client, the third party will begin the Oauth2.0 authorization grant flow to ultimately receive access to Bolt Account APIs.


Term Definition
Authorization Code Code granted to a store’s front-end to be exchanged for an access token and refresh token. The authorization code can be used within 5 minutes of its initial grant.
Access Token Token that allows third-parties to access account data. The access token is multi-use and can be used for up to 1 hour.
Refresh Token Token that allows third-parties to issue new access tokens without prompting the Bolt Account user. The refresh token is single-use and can be used for 1 year.
Client ID A public identifier for third parties. For Bolt, the client ID is the merchant publishable key available on the Merchant Dashboard developers tab. The publishable key is a long string of lower and upper case letters and numbers that consists of three sections.
Client Secret A secret only known to the third party and the Bolt Authorization Server. For Bolt, the client secret is the merchant API key available on the Merchant Dashboard developers tab.


Ensure that you do not store your API Keys in publicly accessible areas such as version control services, client-side code, etc. as they provide access to customer data. Keeping these credentials secure is very important.

OAuth Flow

The following diagram depicts the OAuth flow interactions between the Bolt Account User, the Bolt Login Client, the third-party store frontend and backend, and Bolt’s Authorization Server:

sequenceDiagram participant Bolt Account User participant Store FrontEnd participant Store BackEnd participant Bolt Login Client participant Bolt Authorization Server Store FrontEnd->>+Bolt Login Client: Open up Bolt Login Client Bolt Login Client-->>Bolt Account User: Prompt for Login to Bolt and Authorization for Store Bolt Account User->>Bolt Login Client: Successful Login Bolt Login Client-->>Store FrontEnd: Return Authorization Code Store FrontEnd->>Store BackEnd: Forward Authorization Code Store BackEnd->>Bolt Authorization Server: Get Access Token (v1/oauth/token - Authorization Code) Bolt Authorization Server-->>Store BackEnd: Return OAuth Tokens (Access Token, Refresh Token, ID Token) Store BackEnd-->>Bolt Account API: Get Account Data (v1/account - Access Token)


You will never call the /authorize endpoint directly. This is done by Bolt components, such as the Bolt Login Client.

  1. The store makes a request to Bolt to display a Bolt Login Client.

  2. The Bolt Account user logs into Bolt on the Bolt Login Client and authorizes the store to make requests on their behalf.

  3. The store receives an authorization code. This is a temporary single-use code representing the authorization.

  4. The store requests for an access token by authenticating with Bolt via a client secret, presenting the issued authorization code.

  5. Bolt Authorization Server authenticates the store and validates the authorization code and returns the necessary OAuth Tokens.

  6. The stores uses the issued access token to make requests to Bolt Account APIs.


Bolt Account Authorization is performed via HTTP Basic Auth. Please provide your access token via the basic auth bearer header Authorization: Bearer: ${TOKEN} to all APIs requiring authorization.


Scope is a mechanism in OAuth 2.0 to limit an application’s access to a user’s account. Each OAuth token will be associated with one or more of the following scopes:

Scope Description
openid This scope grants permissions that enable Bolt SSO by granting an ID token JWT that stores account data.
bolt.account.manage This scope grants permissions to perform read/edit/delete actions on Bolt Account data
bolt.account.view This scope grants permissions to perform read-only actions on Bolt Account data

OpenID Connect

OpenID Connect is an identity standard for third parties to initiate OpenID Authentication requests with their authorization servers. It exists as a simple identity layer on top of OAuth 2.0 to allow third parties to verify identity based upon the authentication performed by Bolt.

At Bolt, we use OpenID Connect for Bolt SSO Commerce. Bolt returns an ID token to the third party via the OAuth Token endpoint if the presented authorization grant includes the open_id scope. The ID token can be further decrypted via Bolt’s RSA Public Key.


Bolt’s Public RSA Key is publicly available via Bolt’s /.well-known/openid-configuration endpoint.

  • Sandbox: https://api-sandbox.bolt.com/.well-known/openid-configuration
  • Production: https://api.bolt.com/.well-known/openid-configuration

Filter by Section
Filter by Topic