📍 Bolt Help / Developer Resources / OAuth at Bolt OAuth at Bolt Learn about using Bolt OAuth to access Shopper API data. Page Contents Click to expand. 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. Definitions 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. WARNING 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) WARNING You will never call the /authorize endpoint directly. This is done by Bolt components, such as the Bolt Login Client. The store makes a request to Bolt to display a Bolt Login Client. The Bolt Account user logs into Bolt on the Bolt Login Client and authorizes the store to make requests on their behalf. The store receives an authorization code. This is a temporary single-use code representing the authorization. The store requests for an access token by authenticating with Bolt via a client secret, presenting the issued authorization code. Bolt Authorization Server authenticates the store and validates the authorization code and returns the necessary OAuth Tokens. The stores uses the issued access token to make requests to Bolt Account APIs. TIP 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. Scopes 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. TIP 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
