# Get OAuth token

> Retrieve a new or refresh an existing OAuth token.

Source: https://help.boltapp.com/api-reference/embeddable-checkout-v3/oauth/oauthgettoken

`POST /oauth/token`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "version": "3.3.22",
    "title": "Bolt API Reference",
    "description": "A comprehensive Bolt API reference for interacting with Accounts, Payments, Orders and more.",
    "termsOfService": "https://www.boltapp.com/end-user-terms",
    "contact": {
      "name": "Bolt",
      "email": "merchantsupport@boltapp.com",
      "url": "https://help.boltapp.com/api-bolt/"
    }
  },
  "servers": [
    {
      "url": "https://{environment}.boltapp.com/v3",
      "variables": {
        "environment": {
          "enum": [
            "api",
            "api-sandbox"
          ],
          "default": "api-sandbox"
        }
      }
    }
  ],
  "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": {
      "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.",
            "examples": [
              "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.",
            "examples": [
              "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",
            "examples": [
              "xyzABC123"
            ]
          },
          "grant_type": {
            "description": "The type of OAuth 2.0 grant being utilized.",
            "enum": [
              "authorization_code"
            ],
            "type": "string",
            "examples": [
              "authorization_code"
            ]
          },
          "code": {
            "description": "Fetched value using OTP value from the Authorization Modal.",
            "type": "string",
            "examples": [
              "7GSjMRSHs6Ak7C_zvVW6P2IhZOHxMK7HZKW1fMX85ms"
            ]
          }
        }
      },
      "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.",
            "examples": [
              "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.",
            "examples": [
              "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",
            "examples": [
              "xyzABC123"
            ]
          },
          "grant_type": {
            "description": "The type of OAuth 2.0 grant being utilized.",
            "enum": [
              "refresh_token"
            ],
            "type": "string",
            "examples": [
              "refresh_token"
            ]
          },
          "refresh_token": {
            "description": "The value of the refresh token issued to you in the originating OAuth token request.",
            "type": "string",
            "examples": [
              "4hJYNO4GHvALZoocXoLenfNeFy1RR5ZT6G5JYrFbvkI.Q_PqV0lIszCNoN-85EwD-2nYZOVEepVgJSolx-Jbzrs"
            ]
          }
        }
      },
      "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",
                "examples": [
                  "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"
          }
        ]
      },
      "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",
            "examples": [
              "KCqordmSK6_lpkaXaXfGD8LwnKMGGOYy4Ju2IaBXpJI.CzOF7QOmGGQEgIzBjxOEh1FbRdDpzf9zbm9eHrCZ6zw"
            ]
          },
          "expires_in": {
            "description": "The access token's expiration, in seconds.",
            "type": "integer",
            "examples": [
              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",
            "examples": [
              "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",
            "examples": [
              "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",
            "examples": [
              "bolt.account.manage openid"
            ]
          },
          "token_type": {
            "description": "The token_type will always be bearer.",
            "type": "string",
            "examples": [
              "bearer"
            ]
          }
        }
      },
      "error": {
        "type": "object",
        "required": [
          ".tag",
          "message"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "unauthorized",
              "forbidden",
              "unprocessable_request",
              "not_found"
            ],
            "description": "The type of error returned",
            "examples": [
              "unprocessable_request"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human-readable error message, which might include information specific to the request that was made.",
            "examples": [
              "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",
            "examples": [
              "invalid_input_parameter"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human-readable error message, which might include information specific to the request that was made.",
            "examples": [
              "We were unable to process your request."
            ]
          },
          "field": {
            "type": "string",
            "description": "The field (in its hierarchical form) that is failing validation.",
            "examples": [
              "address.phone"
            ]
          }
        }
      }
    },
    "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"
        }
      }
    },
    "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"
      }
    }
  }
}
```