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:
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