Bolt OAuth API
Use the OAuth API to enable your ecommerce server to make API calls on behalf of a Bolt logged-in shopper.
OpenAPI Specification
openapi: 3.0.0
info:
version: 3.3.22
title: Bolt API Reference Account OAuth API
description: A comprehensive Bolt API reference for interacting with Accounts, Payments, Orders and more.
termsOfService: https://www.bolt.com/end-user-terms
contact:
name: Bolt
email: merchantsupport@bolt.com
url: https://help.bolt.com/api-bolt/
servers:
- url: https://{environment}.bolt.com/v3
variables:
environment:
enum:
- api
- api-sandbox
default: api-sandbox
tags:
- name: OAuth
description: Use the OAuth API to enable your ecommerce server to make API calls on behalf of a Bolt logged-in shopper.
externalDocs:
url: https://help.bolt.com/products/accounts/direct-api/oauth-guide/
paths:
/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'
components:
schemas:
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.bolt.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
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
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.bolt.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
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.
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
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'
examples:
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
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
responses:
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)
securitySchemes:
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