openapi: 3.2.0 info: title: Bolt Financial O Auth API version: '1.0' description: 'Operations tagged OAuth across 3 of this provider''s published API definitions: bolt-financial-bolt-api-openapi.yml, bolt-financial-embeddable-checkout-v1-openapi.yml, bolt-financial-embeddable-checkout-v3-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api.boltapp.com description: The Production URL (Live Data). - url: https://api-sandbox.boltapp.com description: The Sandbox URL (Test Data). - url: https://api-staging.boltapp.com description: The Staging URL (Staged Data). - url: https://{environment}.boltapp.com/v3 variables: environment: enum: - api - api-sandbox default: api-sandbox tags: - name: OAuth description: 'Use this endpoint to retrieve an OAuth token. Use the token to allow your ecommerce server to make calls to the Account endpoint and create a one-click checkout experience for shoppers. See related guide [Fetch OAuth Token](https://help.boltapp.com/products/ignite/api-implementation/endpoints/oauth-guide/). ' paths: /v1/oauth/token: post: description: "Endpoint for receiving access, ID, and refresh tokens from Bolt's OAuth server. \n\nTo use this endpoint, first use the Authorization Code Request flow by using the `authorization_code` Grant Type (`grant_type`). Then, in the event that you would need a second or subsequent code, use the `refresh_token` value returned from a successful request as the `refresh_token` input value in your subsequent `refresh_token` Grant Type (`grant_type`) request.\n\n **Reminder - the Content-Type of this request must be application/x-www-form-urlencoded**\n" operationId: OAuthToken parameters: - $ref: '#/components/parameters/x-publishable-key' requestBody: content: application/x-www-form-urlencoded: examples: authorization_code_request: value: client_id: PUBLISHABLE_KEY_PLACEHOLDER client_secret: API_KEY_PLACEHOLDER code: AUTH_CODE_PLACEHOLDER grant_type: authorization_code scope: bolt.account.manage+openid refresh_token_request: value: client_id: PUBLISHABLE_KEY_PLACEHOLDER client_secret: API_KEY_PLACEHOLDER grant_type: refresh_token refresh_token: REFRESH_TOKEN_PLACEHOLDER scope: bolt.account.view schema: oneOf: - $ref: '#/components/schemas/o_auth_token_input' - $ref: '#/components/schemas/o_auth_token_input_refresh' responses: '200': content: application/json: examples: authorization_code_response: value: access_token: $ACCESS_TOKEN expires_in: 3600 id_token: $ID_TOKEN refresh_token: $REFRESH_TOKEN refresh_token_scope: bolt.account.view scope: bolt.account.manage token_type: bearer refresh_token_response: value: access_token: $NEW_ACCESS_TOKEN expires_in: 3600 refresh_token: $NEW_REFRESH_TOKEN refresh_token_scope: bolt.account.view scope: bolt.account.view token_type: bearer schema: $ref: '#/components/schemas/o_auth_token_response' description: OAuth token response. '400': $ref: '#/components/responses/oauth_400' '403': $ref: '#/components/responses/oauth_403' '422': $ref: '#/components/responses/oauth_422' summary: OAuth Token Endpoint tags: - OAuth security: - X-API-Key: [] - OAuth: - bolt.account.manage - bolt.account.view servers: - url: https://api.boltapp.com description: The Production URL (Live Data). - url: https://api-sandbox.boltapp.com description: The Sandbox URL (Test Data). - url: https://api-staging.boltapp.com description: The Staging URL (Staged Data). /oauth/token: post: summary: Get OAuth token operationId: oauthGetToken x-speakeasy-name-override: GetToken description: Retrieve a new or refresh an existing OAuth token. tags: - OAuth security: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: oneOf: - $ref: '#/components/schemas/authorization-code-request' - $ref: '#/components/schemas/refresh-token-request' examples: authorization-code: $ref: '#/components/examples/authorization-code' refresh-token: $ref: '#/components/examples/refresh-token' responses: '200': description: Access token is successfully fetched content: application/json: schema: $ref: '#/components/schemas/get-access-token-response' 4XX: $ref: '#/components/responses/response-4xx' default: $ref: '#/components/responses/response-default' servers: - url: https://{environment}.boltapp.com/v3 variables: environment: enum: - api - api-sandbox default: api-sandbox components: responses: oauth_422: content: application/json: example: error: invalid _grant error_description: The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. schema: $ref: '#/components/schemas/errors_oauth_server_response' description: Unprocessable request to OAuth Token. oauth_403: content: application/json: examples: request_forbidden: value: error: request_forbidden error_description: The request is forbidden. You are not allowed to perform this action. unsupported_grant_type: value: error: unsupported_grant_type error_description: The grant type is not supported by Bolt’s authorization server. schema: $ref: '#/components/schemas/errors_oauth_server_response' description: Forbidden request to OAuth Token. oauth_400: content: application/json: examples: invalid_request: value: error: invalid_request error_description: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. invalid_scope: value: error: invalid_scope error_description: The request scope is invalid, unknown, or malformed. schema: $ref: '#/components/schemas/errors_oauth_server_response' description: Invalid request to OAuth Token. response-4xx: description: An error has occurred, and further details are contained in the response content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - $ref: '#/components/schemas/field-error' response-default: description: An error has occurred, and no further details are provided (e.g. 5xx errors) schemas: o_auth_token_response: properties: access_token: description: An access token you can use to make requests on behalf of a Bolt Account. type: string expires_in: description: Access token’s expiration in seconds. type: integer id_token: description: A JWT token issued when the request includes the scope open_id. type: string refresh_token: description: A refresh token you can use to issue a brand new access token without obtaining a new authorization code. type: string refresh_token_scope: description: The scope granted to the refresh token. Currently this will always be bolt.account.view. type: string scope: description: The scope granted to access token, depending on the scope granted to the authorization code as well as the scope parameter. Options include `bolt.account.manage`, `bolt.account.view`, `openid`. type: string token_type: description: The token_type will always be bearer. type: string type: object o_auth_token_input: properties: client_id: description: Merchant publishable key which can be found in the merchant dashboard type: string client_secret: description: Your Bolt API Key. type: string code: description: Fetched value using OTP value from the Authorization Modal. type: string grant_type: description: "The type of OAuth 2.0 grant being utilized. \n\nThe value will always be `authorization_code` when exchanging an authorization code for an access token.\n" enum: - authorization_code type: string scope: description: The scope issued to the merchant when receiving an authorization code. Options include `bolt.account.manage`, `bolt.account.view`, `openid`. You can find more information on these options in our [OAuth scope documentation](https://help.boltapp.com/developers/references/bolt-oauth/#scopes). enum: - bolt.account.manage - bolt.account.view - openid type: string state: description: A randomly generated string issued to the merchant when receiving an authorization code used to prevent CSRF attacks type: string required: - grant_type - code - client_id - scope - client_secret title: Authorization Code Request type: object o_auth_token_input_refresh: properties: client_id: description: Merchant publishable key which can be found in the merchant dashboard type: string client_secret: description: Your Bolt API Key. type: string grant_type: description: "The type of OAuth 2.0 grant being utilized. \n\nThe value will always be `refresh_token` when exchanging a refresh token for an access token.\n" enum: - refresh_token type: string refresh_token: description: The value of the refresh token issued to you in the originating OAuth token request. type: string scope: description: The scope issued to the merchant when receiving an authorization code. Options include `bolt.account.manage`, `bolt.account.view`, `openid`. type: string state: description: A randomly generated string issued to the merchant when receiving an authorization code used to prevent CSRF attacks type: string required: - grant_type - client_id - refresh_token - scope - client_secret title: Refresh Token Request type: object errors_oauth_server_response: properties: error: type: string error_description: type: string type: object field-error: type: object description: An error that pertains to validation of a specific field in the request. required: - .tag - message - field properties: .tag: type: string enum: - invalid_input_parameter description: The type of error returned example: invalid_input_parameter message: type: string description: A human-readable error message, which might include information specific to the request that was made. example: We were unable to process your request. field: type: string description: The field (in its hierarchical form) that is failing validation. example: address.phone base-oauth-token-response: type: object properties: access_token: description: An access token you can use to make requests on behalf of a Bolt shopper. type: string example: KCqordmSK6_lpkaXaXfGD8LwnKMGGOYy4Ju2IaBXpJI.CzOF7QOmGGQEgIzBjxOEh1FbRdDpzf9zbm9eHrCZ6zw expires_in: description: The access token's expiration, in seconds. type: integer example: 3600 refresh_token: description: A refresh token you can use to issue a brand new access token without obtaining a new authorization code. type: string example: 4hJYNO4GHvALZoocXoLenfNeFy1RR5ZT6G5JYrFbvkI.Q_PqV0lIszCNoN-85EwD-2nYZOVEepVgJSolx-Jbzrs refresh_token_scope: description: The scope granted to the refresh token. Currently, refreshed token will only grant view permissions. type: string example: bolt.account.view scope: description: The scope granted to access token, depending on the scope granted to the authorization code as well as the scope parameter. Options include `bolt.account.manage`, `bolt.account.view`, `openid`. Multiple values can be returned as space-separated strings. type: string example: bolt.account.manage openid token_type: description: The token_type will always be bearer. type: string example: bearer refresh-token-request: type: object description: Refresh an existing access token, using the refresh token provided in the initial authorization. required: - client_id - client_secret - grant_type - scope - refresh_token properties: client_id: type: string description: The OAuth client ID, which corresponds to the merchant publishable key, which can be retrieved in your Merchant Dashboard. example: 8fd9diIy59sj.IraJdeIgmdsO.fd233434fg2c616cgo932aa6e1e4fc627a9385045gr395222a127gi93c595rg4 client_secret: type: string description: The OAuth client secret, which corresponds the merchant API key, which can be retrieved in your Merchant Dashboard. example: 23ee7ec7301779eaff451d7c6f6cba322499e3c0ec752f800c72a8f99217e3a8 scope: description: The requested scopes. If the request is successful, the OAuth client will be able to perform operations requiring these scopes. externalDocs: description: OAuth Developer Reference url: https://help.boltapp.com/developers/references/bolt-oauth/#scopes type: array items: type: string enum: - bolt.account.manage - bolt.account.view - openid state: description: A randomly generated string sent along with an authorization code. This must be included if provided. It is used to prevent cross-site request forgery (CSRF) attacks. type: string example: xyzABC123 grant_type: description: The type of OAuth 2.0 grant being utilized. enum: - refresh_token type: string example: refresh_token refresh_token: description: The value of the refresh token issued to you in the originating OAuth token request. type: string example: 4hJYNO4GHvALZoocXoLenfNeFy1RR5ZT6G5JYrFbvkI.Q_PqV0lIszCNoN-85EwD-2nYZOVEepVgJSolx-Jbzrs authorization-code-request: type: object description: Perform the initial token exchange, using the authorization code provided by Bolt's Login Modal. required: - client_id - client_secret - grant_type - scope - code properties: client_id: type: string description: The OAuth client ID, which corresponds to the merchant publishable key, which can be retrieved in your Merchant Dashboard. example: 8fd9diIy59sj.IraJdeIgmdsO.fd233434fg2c616cgo932aa6e1e4fc627a9385045gr395222a127gi93c595rg4 client_secret: type: string description: The OAuth client secret, which corresponds the merchant API key, which can be retrieved in your Merchant Dashboard. example: 23ee7ec7301779eaff451d7c6f6cba322499e3c0ec752f800c72a8f99217e3a8 scope: description: The requested scopes. If the request is successful, the OAuth client will be able to perform operations requiring these scopes. externalDocs: description: OAuth Developer Reference url: https://help.boltapp.com/developers/references/bolt-oauth/#scopes type: array items: type: string enum: - bolt.account.manage - bolt.account.view - openid state: description: A randomly generated string sent along with an authorization code. This must be included if provided. It is used to prevent cross-site request forgery (CSRF) attacks. type: string example: xyzABC123 grant_type: description: The type of OAuth 2.0 grant being utilized. enum: - authorization_code type: string example: authorization_code code: description: Fetched value using OTP value from the Authorization Modal. type: string example: 7GSjMRSHs6Ak7C_zvVW6P2IhZOHxMK7HZKW1fMX85ms get-access-token-response: allOf: - type: object properties: id_token: description: A JSON Web Token (JWT) issued when the request includes the scope open_id. type: string example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsaWNlQGV4YW1wbGUuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImV4cCI6MTcwNTY1MTczMSwiZmlyc3RfbmFtZSI6IkFsaWNlIiwiaXNzIjoiaHR0cDovL2FwaS5ib2x0LmNvbSIsImxhc3RfbmFtZSI6IkJha2VyIiwicGhvbmVfbnVtYmVyIjoiKzE0MTU1NTUwMTk5IiwicGhvbmVfbnVtYmVyX3ZlcmlmaWVkIjp0cnVlLCJpYXQiOjE3MDU2NDg0MjF9.Ir0aKx40zfNCZol1DnqchFx9ciHlyZY9y10mndEjOBHhpHif8-7aZl2UoJVs_0Hj-5ArEouUD6n-y1SJD0Wns-gDMoA0Etoc5dT_0zt0Kw5T8FvJWbyKyyGSDEwPFVADIRxDPMpVoHx0C0nwr_GudnIX7YG6p2HCsoGm2C04ZxKpifSixB3-xNB6k9u1ESWh0KjMCYzBQ2x9wbQ_S6kFtio075PFYcZ3iRQz8oD15NsZDd2czzZkRnGTGlpG0sAvScLXMvDDOWBIu-4wvOEOT7avunJQ_rOCYUlyJe7JGh0QllpeJNau8kx-4YGMeFTkeGM_hPIKsRF1e6o_rWp5CMJnmJDPme-zlJxWodyaHNed5XW-4DR7blv_PFOJNrRvymRoTOd74LIpS21GRCNYrphj7N6-TsSfO9hMQ9ehxrgNAryWbVtTM_3VvWyzX-SRa7BcRkS97sokxc04s3cbXra3x6brE3uL1yoOWNf8GDZNkv1uUAnrOZcTuLacrPjkQgOPb-chMiWS1L0Zd1wX3rqpeCyEswsGKxRRkpgwoBaVVQmLB9m51B6SXEvURTcy2Hx8KzgfXQ_-uC-KrniQxWzYms8A1lypKXkEcyMD2E4Q7EB4UeD2qZAk4tZo611uHegaHaEM7EQyFN3nxvibaqFpXzdxVmOCX0_wQr1nDNA - $ref: '#/components/schemas/base-oauth-token-response' error: type: object required: - .tag - message properties: .tag: type: string enum: - unauthorized - forbidden - unprocessable_request - not_found description: The type of error returned example: unprocessable_request message: type: string description: A human-readable error message, which might include information specific to the request that was made. example: We were unable to process your request. parameters: x-publishable-key: description: The publicly viewable identifier used to identify a merchant division. This key is found in the Developer > API section of the Bolt Merchant Dashboard [RECOMMENDED]. in: header name: X-Publishable-Key required: false schema: type: string examples: authorization-code: summary: Exchange an authorization code description: Perform the initial token exchange, using the authorization code provided by Bolt's Login Modal. value: client_id: 8fd9diIy59sj.IraJdeIgmdsO.fd233434fg2c616cgo932aa6e1e4fc627a9385045gr395222a127gi93c595rg4 client_secret: 23ee7ec7301779eaff451d7c6f6cba322499e3c0ec752f800c72a8f99217e3a8 scope: - bolt.account.manage - bolt.account.view - openid state: xyzABC123 grant_type: authorization_code code: 7GSjMRSHs6Ak7C_zvVW6P2IhZOHxMK7HZKW1fMX85ms refresh-token: summary: Refresh an existing token. description: Refresh an existing access token, using the refresh token provided in the initial authorization. value: client_id: 8fd9diIy59sj.IraJdeIgmdsO.fd233434fg2c616cgo932aa6e1e4fc627a9385045gr395222a127gi93c595rg4 client_secret: 23ee7ec7301779eaff451d7c6f6cba322499e3c0ec752f800c72a8f99217e3a8 scope: - bolt.account.view state: xyzABC123 grant_type: refresh_token refresh_token: 4hJYNO4GHvALZoocXoLenfNeFy1RR5ZT6G5JYrFbvkI.Q_PqV0lIszCNoN-85EwD-2nYZOVEepVgJSolx-Jbzrs securitySchemes: OAuth: description: 'Bolt utilizes the OAuth flow that developers can use to attain access to Bolt Account data via APIs. For all APIs that require authorization, please provide your `access_token` returned from `/v1/oauth/token` via the basic auth bearer header `Authorization: bearer ${TOKEN}`. [Read more about the OAuth token endpoint.](/api-bolt/#tag/OAuth) ' flows: authorizationCode: authorizationUrl: https://api.boltapp.com/v1/oauth/authorize refreshUrl: https://api.boltapp.com/v1/oauth/token scopes: 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: This scope grants permissions that enable Bolt SSO by granting an id token JWT that stores account data. Not used in v1/account endpoints tokenUrl: https://api.boltapp.com/v1/oauth/token type: oauth2 X-API-Key: description: Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard. in: header name: X-API-Key type: apiKey api-key: type: apiKey in: header name: X-API-Key oauth: flows: authorizationCode: authorizationUrl: /v1/oauth/authorize refreshUrl: /v1/oauth/token tokenUrl: /v1/oauth/token scopes: 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: This scope grants permissions that enable Bolt Single Sign-On (SSO) by granting a JSON Web Token (JWT) that stores account data. type: oauth2 x-refined-from: - bolt-financial-bolt-api-openapi.yml - bolt-financial-embeddable-checkout-v1-openapi.yml - bolt-financial-embeddable-checkout-v3-openapi.yml