# OAuth Token Endpoint

> Endpoint for receiving access, ID, and refresh tokens from Bolt's OAuth server. To 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. **Reminder - the Content-Type of this request must be application/x-www-form-urlencoded**

Source: https://help.boltapp.com/api-reference/embeddable-checkout-v1/oauth/oauthtoken

`POST /v1/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": "1.0.1",
    "title": "Embedded API Reference",
    "description": "Postman Collection:\n\n[![](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/9136127-55d2bde1-a248-473f-95b5-64cfd02fb445?action=collection%2Ffork&collection-url=entityId%3D9136127-55d2bde1-a248-473f-95b5-64cfd02fb445%26entityType%3Dcollection%26workspaceId%3D78beee89-4238-4c5f-bd1f-7e98978744b4#?env%5BBolt%20Sandbox%20Environment%5D=W3sia2V5IjoiYXBpX2Jhc2VfdXJsIiwidmFsdWUiOiJodHRwczovL2FwaS1zYW5kYm94LmJvbHQuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRrX2Jhc2UiLCJ2YWx1ZSI6Imh0dHBzOi8vc2FuZGJveC5ib2x0dGsuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFwaV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggQVBJIGtleT4iLCJ0eXBlIjoic2VjcmV0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwdWJsaXNoYWJsZV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggcHVibGlzaGFibGUga2V5PiIsInR5cGUiOiJkZWZhdWx0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJkaXZpc2lvbl9pZCIsInZhbHVlIjoiPHJlcGxhY2Ugd2l0aCB5b3VyIEJvbHQgU2FuZGJveCBwdWJsaWMgZGl2aXNpb24gSUQ+IiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfV0=)\n\n## About\nThe Embedded API reference is a consolidation of critical APIs that a developer will use when integrating with Bolt's Embedded Accounts product suite.\n"
  },
  "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)."
    }
  ],
  "security": [
    {
      "X-API-Key": []
    },
    {
      "OAuth": [
        "bolt.account.manage",
        "bolt.account.view"
      ]
    }
  ],
  "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"
        ]
      }
    }
  },
  "components": {
    "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"
        }
      }
    },
    "schemas": {
      "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"
      },
      "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"
      },
      "errors_oauth_server_response": {
        "properties": {
          "error": {
            "type": "string"
          },
          "error_description": {
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "responses": {
      "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."
      },
      "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_422": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errors_oauth_server_response"
            },
            "examples": {
              "default": {
                "value": {
                  "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."
                }
              }
            }
          }
        },
        "description": "Unprocessable request to OAuth Token."
      }
    },
    "securitySchemes": {
      "OAuth": {
        "description": "Bolt utilizes the OAuth flow that developers can use to attain access to Bolt Account data via APIs.\nFor all APIs that require authorization, please provide your `access_token` returned from `/v1/oauth/token` via the basic auth bearer header `Authorization: bearer ${TOKEN}`.\n[Read more about the OAuth token endpoint.](/api-bolt/#tag/OAuth)\n",
        "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"
      }
    }
  }
}
```